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

package/commands/generate-bdd.md

@@ -161,7 +161,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`)
@@ -173,7 +173,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`
@@ -204,7 +204,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).
@@ -219,19 +219,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.
 
 ---
 
@@ -297,7 +319,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).
 
 ---
 
@@ -331,7 +353,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}
@@ -811,7 +834,7 @@ After generating all `.feature` files, create or update `{paths.trace_dir}/{UC-I
 
 **TSV columns (tab-separated, one header row + one data row per scenario):**
 ```
-sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
+sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tdev_selftest\tdev_selftest_at\tqc_status\tqc_run_at\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
 ```
 
 **Rules:**
@@ -819,7 +842,7 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 - If file exists (re-generation) → for each SC in the new `.feature`:
   - SC already in `.tsv` AND `spec_ver` is unchanged → update only: `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Leave all other columns unchanged.
   - SC already in `.tsv` AND `spec_ver` changed (scenario was modified) → update: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` AND set `status = DRIFT` immediately (so the TSV reflects drift without waiting for `/validate-traces`). Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` unchanged.
-  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` all set to `—`.
+  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `tech_doc_revision` all set to `—`.
   - SC no longer in `.feature` (removed) → delete its row.
 
 **Values to write for each scenario:**
@@ -833,6 +856,10 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 | `implemented_by` | `—` |
 | `test_count` | `—` |
 | `test_classes` | `—` |
+| `dev_selftest` | `—` (no tests run yet) |
+| `dev_selftest_at` | `—` |
+| `qc_status` | `—` (official QC automation result — set by `/qc-run-test`) |
+| `qc_run_at` | `—` |
 | `prd_version` | `@trace.prd_version` from `.feature` header |
 | `bdd_version` | `@trace.bdd_version` from `.feature` header |
 | `tech_doc_revision` | `—` |
@@ -842,6 +869,27 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 | `status` | `UNTRACKED` |
 | `last_updated` | today `YYYY-MM-DD` |
 
+## Refresh Panel Mirror
+# Refresh Living Docs panel mirror *(local, umbrella mode)*
+
+*Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
+the service `.trace/` IS the panel location, so nothing to mirror.*
+
+After updating the authoritative service TSV(s) at `{paths.trace_dir}`:
+
+1. Resolve `panel_mirror = ./.trace` at the **current workspace root** (where this command runs).
+2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
+   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+   (create the dir; overwrite). Use `active_service` for `{service-name}`.
+
+This keeps the open workspace's Living Docs panel current **between syncs** — it is a
+**local convenience mirror only**. The *canonical* report in the spec module
+(`{spec_source}/.living-docs/`) and the merged `trace-report.json` are rebuilt by
+`/sync` or `/validate-traces` (those need every service's data, so a single per-UC
+command cannot produce them). For orchestrated commands, do this once in the orchestrator
+after all sub-agents return — not inside each sub-agent.
+
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -880,15 +928,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}` |
@@ -930,4 +985,6 @@ Next (umbrella):
   → /review-context {feature-file} to verify coverage
   → /generate-tech-docs {feature-file}
   → /generate-code {feature-file}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/commands/generate-bdd.tmpl

@@ -458,7 +458,7 @@ After generating all `.feature` files, create or update `{paths.trace_dir}/{UC-I
 
 **TSV columns (tab-separated, one header row + one data row per scenario):**
 ```
-sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
+sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tdev_selftest\tdev_selftest_at\tqc_status\tqc_run_at\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
 ```
 
 **Rules:**
@@ -466,7 +466,7 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 - If file exists (re-generation) → for each SC in the new `.feature`:
   - SC already in `.tsv` AND `spec_ver` is unchanged → update only: `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Leave all other columns unchanged.
   - SC already in `.tsv` AND `spec_ver` changed (scenario was modified) → update: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` AND set `status = DRIFT` immediately (so the TSV reflects drift without waiting for `/validate-traces`). Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` unchanged.
-  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` all set to `—`.
+  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `tech_doc_revision` all set to `—`.
   - SC no longer in `.feature` (removed) → delete its row.
 
 **Values to write for each scenario:**
@@ -480,6 +480,10 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 | `implemented_by` | `—` |
 | `test_count` | `—` |
 | `test_classes` | `—` |
+| `dev_selftest` | `—` (no tests run yet) |
+| `dev_selftest_at` | `—` |
+| `qc_status` | `—` (official QC automation result — set by `/qc-run-test`) |
+| `qc_run_at` | `—` |
 | `prd_version` | `@trace.prd_version` from `.feature` header |
 | `bdd_version` | `@trace.bdd_version` from `.feature` header |
 | `tech_doc_revision` | `—` |
@@ -489,6 +493,9 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 | `status` | `UNTRACKED` |
 | `last_updated` | today `YYYY-MM-DD` |
 
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
+
 ## Output
 
 {{include:steps/report-footer.md}}
@@ -517,4 +524,6 @@ Next (umbrella):
   → /review-context {feature-file} to verify coverage
   → /generate-tech-docs {feature-file}
   → /generate-code {feature-file}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/commands/generate-code.md

@@ -163,7 +163,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`)
@@ -175,7 +175,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`
@@ -206,7 +206,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).
@@ -221,19 +221,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.
 
 ---
 
@@ -299,7 +321,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).
 
 ---
 
@@ -333,7 +355,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}
@@ -380,6 +403,7 @@ Read:
 1. The scoped `.feature` file only
 2. Tech-doc at `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` (if exists)
 3. CLAUDE.md §architecture + §coding_standards
+4. **(FE/App only)** Design Spec at `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-*{slug}.md` (if exists) — source of screens, component inventory, and the per-screen Figma frame links.
 
 ---
 
@@ -403,6 +427,51 @@ Load System BDD for this UC: find `{specs_dir}/{domain}/system/{TICKET-ID}*.feat
 Extract all `Then` clauses → collect implied response shapes and error states.
 If System BDD not found → warn: "System BDD not found — mock layer will use placeholder fixtures." Continue.
 
+**Then run the Figma Dev Mode MCP Check below** before generating any UI — the Design
+Spec's frame links are the visual contract, and the local MCP reads them with far more
+fidelity than a plain web link.
+
+---
+
+## Figma Dev Mode MCP Check *(FE/App UI generation only)*
+
+*Run this only when `platform` is `web`/`app` AND generating UI (`--phase=ui`, or default
+mode for an FE/App feature). Skip entirely for BE / `system` platform.*
+
+The PO authored the Design Spec from **Figma web links** (read-only, limited). For
+codegen, the **local Figma Dev Mode MCP server** (built into the Figma **desktop app**)
+gives far more: exact layout, design **variables/tokens**, **Code Connect** component
+mappings, selection context, and code snippets — things a web URL alone cannot return.
+
+**Step 1 — Detect the local MCP.** Check whether a Figma Dev Mode MCP server is connected
+(a `get_design_context` / `get_code` style Figma tool is available via MCP).
+
+**Step 2 — If NOT connected → suggest the dev enable it, then wait:**
+
+```
+🎨 Figma Dev Mode MCP not detected.
+   For accurate FE code (real tokens, components, Code Connect), use the LOCAL server:
+
+   1. Open the Figma DESKTOP app (not the browser)
+   2. Open the file/frame for this feature
+   3. Enable the Dev Mode MCP server:
+        Figma menu → Preferences → "Enable Dev Mode MCP Server"
+        (requires Dev or Full seat; server runs at http://127.0.0.1:3845)
+   4. Make sure this MCP server is added in your Claude Code MCP config
+   5. Select the frame for the screen you're implementing, then continue
+
+   Type C to continue once enabled, or S to skip (fall back to web links + text spec).
+```
+
+- `C` → re-detect; if now connected → proceed using the local MCP.
+- `S` → proceed in **fallback mode**: use the Design Spec's web frame links + textual spec
+  only; add a ⚠️ note in the final report that UI was generated without local Figma fidelity.
+
+**Step 3 — When the local MCP IS connected:** for each screen being implemented, pull the
+selected frame via the Figma MCP and ground the UI on the returned layout, variables, and
+Code Connect mappings. Prefer Code-Connect-mapped components over inventing markup; use the
+real token names, not hardcoded values.
+
 **If `--phase=integration`:**
 Read tech-doc `@trace.status` from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
 If `draft` or `in-review` → warn:
@@ -425,7 +494,7 @@ Read `{paths.trace_dir}/{UC-ID}.tsv` if it exists. For each scenario row, note i
 | `UNTRACKED` | `implemented_by == —` | Generate — scenario has no code yet |
 | `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario updated since last codegen |
 | `OK` | implemented + tested | Skip unless explicitly re-generating |
-| `GAP` | implemented, no tests | Skip codegen — already coded; run `/generate-tests` instead |
+| `GAP` | implemented, no tests | Skip codegen — already coded; run `/dev-gen-test` instead |
 
 Use these statuses to populate the **Scenarios** count in the CHECKPOINT plan (`{X} new, {Y} drifted, {Z} synced-skip`).
 If `.tsv` does not exist → treat all scenarios as `UNTRACKED`.
@@ -579,9 +648,30 @@ Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find t
 | `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
 | `last_updated` | today `YYYY-MM-DD` |
 
-Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`) unchanged.
+Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`) unchanged.
 `status` is computed by `/validate-traces` — do not set here.
 
+## Refresh Panel Mirror
+# Refresh Living Docs panel mirror *(local, umbrella mode)*
+
+*Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
+the service `.trace/` IS the panel location, so nothing to mirror.*
+
+After updating the authoritative service TSV(s) at `{paths.trace_dir}`:
+
+1. Resolve `panel_mirror = ./.trace` at the **current workspace root** (where this command runs).
+2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
+   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+   (create the dir; overwrite). Use `active_service` for `{service-name}`.
+
+This keeps the open workspace's Living Docs panel current **between syncs** — it is a
+**local convenience mirror only**. The *canonical* report in the spec module
+(`{spec_source}/.living-docs/`) and the merged `trace-report.json` are rebuilt by
+`/sync` or `/validate-traces` (those need every service's data, so a single per-UC
+command cannot produce them). For orchestrated commands, do this once in the orchestrator
+after all sub-agents return — not inside each sub-agent.
+
+
 ## Commit
 ```bash
 git add {files}
@@ -626,15 +716,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}` |
@@ -658,6 +755,7 @@ Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
 Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
 fe_phase : {ui | integrated | —}
+Figma    : {local Dev Mode MCP (grounded) | ⚠️ web links + text spec only (no local MCP) | n/a for BE}   ← FE/App UI only
 
 Next:
   --phase=ui done:
@@ -667,9 +765,11 @@ Next:
 
   --phase=integration done:
     → /review-code {UC-ID}   ← code review required
-    → /generate-tests {UC-ID}  ← integration test suite
+    → /dev-gen-test {UC-ID}  ← integration test suite
 
   Default (no phase flag):
     → /review-code {UC-ID}   ← code review required before tests
-    → /generate-tests {UC-ID}
+    → /dev-gen-test {UC-ID}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/commands/generate-code.tmpl

@@ -27,6 +27,7 @@ Read:
 1. The scoped `.feature` file only
 2. Tech-doc at `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` (if exists)
 3. CLAUDE.md §architecture + §coding_standards
+4. **(FE/App only)** Design Spec at `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-*{slug}.md` (if exists) — source of screens, component inventory, and the per-screen Figma frame links.
 
 ---
 
@@ -50,6 +51,51 @@ Load System BDD for this UC: find `{specs_dir}/{domain}/system/{TICKET-ID}*.feat
 Extract all `Then` clauses → collect implied response shapes and error states.
 If System BDD not found → warn: "System BDD not found — mock layer will use placeholder fixtures." Continue.
 
+**Then run the Figma Dev Mode MCP Check below** before generating any UI — the Design
+Spec's frame links are the visual contract, and the local MCP reads them with far more
+fidelity than a plain web link.
+
+---
+
+## Figma Dev Mode MCP Check *(FE/App UI generation only)*
+
+*Run this only when `platform` is `web`/`app` AND generating UI (`--phase=ui`, or default
+mode for an FE/App feature). Skip entirely for BE / `system` platform.*
+
+The PO authored the Design Spec from **Figma web links** (read-only, limited). For
+codegen, the **local Figma Dev Mode MCP server** (built into the Figma **desktop app**)
+gives far more: exact layout, design **variables/tokens**, **Code Connect** component
+mappings, selection context, and code snippets — things a web URL alone cannot return.
+
+**Step 1 — Detect the local MCP.** Check whether a Figma Dev Mode MCP server is connected
+(a `get_design_context` / `get_code` style Figma tool is available via MCP).
+
+**Step 2 — If NOT connected → suggest the dev enable it, then wait:**
+
+```
+🎨 Figma Dev Mode MCP not detected.
+   For accurate FE code (real tokens, components, Code Connect), use the LOCAL server:
+
+   1. Open the Figma DESKTOP app (not the browser)
+   2. Open the file/frame for this feature
+   3. Enable the Dev Mode MCP server:
+        Figma menu → Preferences → "Enable Dev Mode MCP Server"
+        (requires Dev or Full seat; server runs at http://127.0.0.1:3845)
+   4. Make sure this MCP server is added in your Claude Code MCP config
+   5. Select the frame for the screen you're implementing, then continue
+
+   Type C to continue once enabled, or S to skip (fall back to web links + text spec).
+```
+
+- `C` → re-detect; if now connected → proceed using the local MCP.
+- `S` → proceed in **fallback mode**: use the Design Spec's web frame links + textual spec
+  only; add a ⚠️ note in the final report that UI was generated without local Figma fidelity.
+
+**Step 3 — When the local MCP IS connected:** for each screen being implemented, pull the
+selected frame via the Figma MCP and ground the UI on the returned layout, variables, and
+Code Connect mappings. Prefer Code-Connect-mapped components over inventing markup; use the
+real token names, not hardcoded values.
+
 **If `--phase=integration`:**
 Read tech-doc `@trace.status` from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
 If `draft` or `in-review` → warn:
@@ -72,7 +118,7 @@ Read `{paths.trace_dir}/{UC-ID}.tsv` if it exists. For each scenario row, note i
 | `UNTRACKED` | `implemented_by == —` | Generate — scenario has no code yet |
 | `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario updated since last codegen |
 | `OK` | implemented + tested | Skip unless explicitly re-generating |
-| `GAP` | implemented, no tests | Skip codegen — already coded; run `/generate-tests` instead |
+| `GAP` | implemented, no tests | Skip codegen — already coded; run `/dev-gen-test` instead |
 
 Use these statuses to populate the **Scenarios** count in the CHECKPOINT plan (`{X} new, {Y} drifted, {Z} synced-skip`).
 If `.tsv` does not exist → treat all scenarios as `UNTRACKED`.
@@ -226,9 +272,12 @@ Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find t
 | `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
 | `last_updated` | today `YYYY-MM-DD` |
 
-Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`) unchanged.
+Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`) unchanged.
 `status` is computed by `/validate-traces` — do not set here.
 
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
+
 ## Commit
 ```bash
 git add {files}
@@ -245,6 +294,7 @@ Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
 Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
 fe_phase : {ui | integrated | —}
+Figma    : {local Dev Mode MCP (grounded) | ⚠️ web links + text spec only (no local MCP) | n/a for BE}   ← FE/App UI only
 
 Next:
   --phase=ui done:
@@ -254,9 +304,11 @@ Next:
 
   --phase=integration done:
     → /review-code {UC-ID}   ← code review required
-    → /generate-tests {UC-ID}  ← integration test suite
+    → /dev-gen-test {UC-ID}  ← integration test suite
 
   Default (no phase flag):
     → /review-code {UC-ID}   ← code review required before tests
-    → /generate-tests {UC-ID}
+    → /dev-gen-test {UC-ID}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```