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

package/ARCHITECTURE.md

@@ -50,19 +50,26 @@
 ┌──────────────────────────────────────────────────────────────────────┐
 │  LAYER 4 — EXECUTION                            (command logic)      │
 │                                                                      │
-│  DISCOVERY        PRD / BDD           CODE / TEST     DEBUG          │
+│  DISCOVERY        PRD / BDD           CODE / DEV-CHECK  DEBUG        │
 │  /define-product  /generate-prd       /generate-code  /fix-bug      │
-│                   /refine-prd         /generate-tests /debug        │
-│                   /generate-bdd       /run-tests      /validate-    │
-│                   /generate-tech-docs /smoke-test      traces       │
+│                   /refine-prd         /dev-gen-test   /debug        │
+│                   /generate-bdd       /dev-run-test   /validate-    │
+│                   /generate-tech-docs /dev-smoke-test    traces     │
 │                   /review-code        /setup-ai-first               │
+│                                                                      │
+│  Lưu ý: /dev-gen-test, /dev-run-test, /dev-smoke-test là dev        │
+│  self-check / smoke (dev tự kiểm code của mình), KHÔNG phải bộ      │
+│  test QC chính thức — QC là một flow riêng chạy sau.                │
 └──────────────────────────────────────────────────────────────────────┘
                                │
 ┌──────────────────────────────────────────────────────────────────────┐
 │  LAYER 5 — OUTPUT                       (artifacts in consumer proj) │
 │                                                                      │
-│  specs/product-definition/   specs/prd/   specs/bdd/               │
-│  tech-docs/                  src/         .trace/   .agent/review/ │
+│  Spec module (cross-team, via {spec_source}):                       │
+│    specs/product-definition/  specs/prd/  specs/bdd/                │
+│    specs/tech-docs/ (API contract)   .living-docs/ (gitignored)     │
+│  Service submodule (per-service):                                   │
+│    src/   .trace/*.tsv (authoritative, committed)   .agent/review/  │
 └──────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -171,8 +178,8 @@ Main session (orchestrator — lightweight, chỉ coordinate)
   ├─ spawn codegen-agent ──→ /generate-code UC1 (own context window)
   │    └─ returns: src/ changes
   │
-  └─ spawn test-agent ──→ /generate-tests UC1 (own context window)
-       └─ returns: test files
+  └─ spawn test-agent ──→ /dev-gen-test UC1 (own context window)
+       └─ returns: dev self-check test files (smoke, không phải QC)
 
 Benefits:
   - Main session không bị bloat bởi large file reads
@@ -222,7 +229,11 @@ spec-driven-dev/
     └── platform-guide.template.md
 ```
 
-> Build output (gitignored): `commands/*.md`, `skills/**/SKILL.md`, and `core/` (the distributable copied into a consumer's `.agent/` by `--init`). Consumer-side tester artifacts live in the shared spec repo under `feedback/bug-reports/` and `feedback/bdd-proposals/`.
+> Build output (gitignored): `commands/*.md`, `skills/**/SKILL.md`, and `core/` (the distributable copied into a consumer's `.agent/` by `--init`). Consumer-side tester artifacts live in the shared spec repo under `feedback/bug-reports/` and `feedback/bdd-proposals/`. In umbrella mode the **API contract (tech-docs)** is a **cross-team artifact**: khi `setup.spec_source` được set, tech-docs LUÔN route về `{spec_source}/specs/tech-docs/` (giống PRD / design-spec / domain-knowledge), KHÔNG per-service — để FE/App đọc contract qua spec submodule ở `/generate-code --phase=integration`. Chỉ khi không có `spec_source` thì tech-docs mới nằm per-service.
+
+> **Living Docs / trace data location**: `.trace/*.tsv` của mỗi service là **authoritative** và được commit trong chính SERVICE submodule. Canonical report của Living Docs (`trace-report.json` + bản TSV mirror đã namespaced) được sinh vào SPEC MODULE tại `{spec_source}/.living-docs/` (gitignored) bởi `/sync` hoặc `/validate-traces`. Ngoài ra một panel mirror cục bộ tại `./.trace` của workspace hiện tại cũng được ghi để VS Code panel resolve được data ngay cả khi mở bên trong một service submodule (không chỉ ở umbrella root). Lý do: spec module được mount vào mọi umbrella/service workspace, nên nó là nơi chung, luôn resolve được cho cross-team dashboard.
+>
+> Trace TSV schema có thêm 2 cột `dev_selftest` (pass/fail/not_run) và `dev_selftest_at`, được set bởi `/dev-run-test` và surface trong Living Docs report như tín hiệu **dev self-check** (không phải coverage QC chính thức).
 
 ---
 

package/bin/index.js

@@ -204,7 +204,6 @@ if (isInit) {
           `    path: "${s.name}"`,
           `    module: "${s.module || 'TODO'}"`,
           `    specs_dir: "${s.name}/specs/bdd"`,
-          `    tech_docs_dir: "${s.name}/specs/tech-docs"`,
         ].join('\n')).join('\n');
       } else {
         servicesBlock = [
@@ -212,7 +211,6 @@ if (isInit) {
           `  #   path: "{service-submodule-dir}"`,
           `  #   module: "{stack-module}"`,
           `  #   specs_dir: "{service-dir}/specs/bdd"`,
-          `  #   tech_docs_dir: "{service-dir}/specs/tech-docs"`,
         ].join('\n');
       }
 
@@ -234,6 +232,7 @@ if (isInit) {
         `paths:`,
         `  prd_dir:              "${specSrc}/specs/prd"`,
         `  design_spec_dir:      "${specSrc}/specs/design-spec"`,
+        `  tech_docs_dir:        "${specSrc}/specs/tech-docs"   # API contract — shared (BE pushes here, FE/App read via /sync)`,
         `  domain_knowledge_dir: "${specSrc}/specs/domain-knowledge"`,
         `  business_dictionary:  "${specSrc}/specs/domain-knowledge/business-dictionary.md"`,
         `  core_entities:        "${specSrc}/specs/domain-knowledge/core-entities.md"`,

package/commands/debug.md

@@ -166,7 +166,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`)
@@ -178,13 +178,14 @@ 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` — **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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **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.
 
 ---
 
@@ -208,7 +209,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).
@@ -301,7 +302,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).
 
 ---
 
@@ -605,13 +606,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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}` |
@@ -722,7 +723,7 @@ If `lessons_path` does not exist, create it with this header first:
 | code-gen | /generate-code output |
 | bdd | /generate-bdd output |
 | tech-docs | /generate-tech-docs output |
-| tests | /generate-tests output |
+| tests | /dev-gen-test output |
 | prd | /generate-prd, /refine-prd output |
 | general | every command |
 

package/commands/define-product.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,13 +175,14 @@ 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` — **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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **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.
 
 ---
 
@@ -205,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).
@@ -298,7 +299,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).
 
 ---
 
@@ -539,13 +540,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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}` |

package/commands/{generate-tests.md → dev-gen-test.md}

@@ -1,4 +1,10 @@
-# /generate-tests — Generate Unit & Integration Tests
+# /dev-gen-test — Generate Dev Self-Check Tests
+
+> **Scope — dev self-check (smoke), not the official test suite.** These tests let the
+> developer quickly verify their own generated code against the BDD scenarios. They are a
+> developer self-check, **not** the QC/dev-team's authoritative test suite (that has its
+> own separate flow, implemented elsewhere). Results surface to the Living Docs dashboard
+> as a **dev self-test** signal so QC can see the dev already ran their own checks.
 
 ## Gate
 # Gate — Universal Entry Procedure
@@ -163,7 +169,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,13 +181,14 @@ 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` — **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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **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.
 
 ---
 
@@ -205,7 +212,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).
@@ -298,7 +305,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).
 
 ---
 
@@ -809,9 +816,33 @@ After generating all test files, update `{paths.trace_dir}/{UC-ID}.tsv` — for
 |--------|-------|
 | `test_count` | number of test methods covering this SC |
 | `test_classes` | comma-separated test class / describe-block names |
+| `dev_selftest` | `not_run` (tests now exist but have not been executed — `/dev-run-test` sets pass/fail) |
 | `last_updated` | today `YYYY-MM-DD` |
 
-Leave all other columns unchanged.
+Leave all other columns unchanged (including `dev_selftest_at`, which `/dev-run-test` owns).
+
+---
+
+## 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.
+
 
 ---
 
@@ -855,13 +886,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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}` |
@@ -880,9 +911,11 @@ Next   : {suggested command with example arguments}
 
 
 ```
-/generate-tests Complete — {UC-ID} ({active_module})
+/dev-gen-test Complete — {UC-ID} ({active_module})
   ✅ {TestClass1} ({N} tests)
   ✅ {TestClass2} ({N} tests)
 Trace: {paths.trace_dir}/{UC-ID}.tsv updated
-Next: /run-tests {UC-ID}
+Next: /dev-run-test {UC-ID}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/commands/{generate-tests.tmpl → dev-gen-test.tmpl}

@@ -1,4 +1,10 @@
-# /generate-tests — Generate Unit & Integration Tests
+# /dev-gen-test — Generate Dev Self-Check Tests
+
+> **Scope — dev self-check (smoke), not the official test suite.** These tests let the
+> developer quickly verify their own generated code against the BDD scenarios. They are a
+> developer self-check, **not** the QC/dev-team's authoritative test suite (that has its
+> own separate flow, implemented elsewhere). Results surface to the Living Docs dashboard
+> as a **dev self-test** signal so QC can see the dev already ran their own checks.
 
 ## Gate
 {{include:steps/gate.md}}
@@ -457,9 +463,15 @@ After generating all test files, update `{paths.trace_dir}/{UC-ID}.tsv` — for
 |--------|-------|
 | `test_count` | number of test methods covering this SC |
 | `test_classes` | comma-separated test class / describe-block names |
+| `dev_selftest` | `not_run` (tests now exist but have not been executed — `/dev-run-test` sets pass/fail) |
 | `last_updated` | today `YYYY-MM-DD` |
 
-Leave all other columns unchanged.
+Leave all other columns unchanged (including `dev_selftest_at`, which `/dev-run-test` owns).
+
+---
+
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
 
 ---
 
@@ -468,9 +480,11 @@ Leave all other columns unchanged.
 {{include:steps/report-footer.md}}
 
 ```
-/generate-tests Complete — {UC-ID} ({active_module})
+/dev-gen-test Complete — {UC-ID} ({active_module})
   ✅ {TestClass1} ({N} tests)
   ✅ {TestClass2} ({N} tests)
 Trace: {paths.trace_dir}/{UC-ID}.tsv updated
-Next: /run-tests {UC-ID}
+Next: /dev-run-test {UC-ID}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/{core/commands/run-tests.md → commands/dev-run-test.md}

@@ -1,4 +1,10 @@
-# /run-tests — Run Tests & Report Results
+# /dev-run-test — Run Dev Self-Check Tests & Report Results
+
+> **Scope — dev self-check (smoke), not the official test suite.** Runs the tests produced
+> by `/dev-gen-test` so the developer can confirm their own code works before review. This
+> is a developer self-check, **not** the QC/dev-team's authoritative test run (separate flow).
+> The pass/fail is published to Living Docs as a **dev self-test** signal — it tells QC the
+> dev ran their checks; it is NOT a statement of official test coverage.
 
 ## Gate
 # Gate — Universal Entry Procedure
@@ -163,7 +169,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,13 +181,14 @@ 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` — **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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **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.
 
 ---
 
@@ -205,7 +212,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).
@@ -298,7 +305,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).
 
 ---
 
@@ -522,6 +529,44 @@ xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhon
 
 ---
 
+## Write Trace State
+
+After the run, persist results to the **authoritative TSV** in the service so they reach
+the Living Docs report at the spec module (via `/sync` + `/validate-traces`). The test
+files themselves stay in the service — only the run *status* is reported.
+
+Update `{paths.trace_dir}/{UC-ID}.tsv` — for each scenario row (matched by `sc_id` via its
+test's `@trace.verifies={UC-ID}-SC{N}` tag):
+
+| Column | Value |
+|--------|-------|
+| `dev_selftest` | `pass` if all tests for this SC passed · `fail` if any failed · `not_run` if its tests were skipped/absent |
+| `dev_selftest_at` | today `YYYY-MM-DD` |
+
+Leave all other columns unchanged. `dev_selftest`/`dev_selftest_at` are orthogonal to `status`
+(OK/GAP/DRIFT/UNTRACKED): `status` tracks *coverage*, `dev_selftest` tracks the latest *run result*.
+
+## 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
@@ -562,13 +607,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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}` |
@@ -587,7 +632,7 @@ Next   : {suggested command with example arguments}
 
 
 ```
-/run-tests Report — {UC-ID} ({active_module})
+/dev-run-test Report — {UC-ID} ({active_module})
 ✅ Passed: {N} | ❌ Failed: {M} | ⏭️ Skipped: {K} | Duration: {X}s
 
 ## Failed Tests
@@ -597,7 +642,11 @@ Next   : {suggested command with example arguments}
 ## Recommendations
 {specific fix per failure}
 
+Trace: {paths.trace_dir}/{UC-ID}.tsv updated (dev_selftest, dev_selftest_at)
+
 Next:
   All tests pass → /review-code {UC-ID}
   Tests fail     → /fix-bug {TICKET_ID} (real bug) or fix test (wrong expectation)
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/commands/{run-tests.tmpl → dev-run-test.tmpl}

@@ -1,4 +1,10 @@
-# /run-tests — Run Tests & Report Results
+# /dev-run-test — Run Dev Self-Check Tests & Report Results
+
+> **Scope — dev self-check (smoke), not the official test suite.** Runs the tests produced
+> by `/dev-gen-test` so the developer can confirm their own code works before review. This
+> is a developer self-check, **not** the QC/dev-team's authoritative test run (separate flow).
+> The pass/fail is published to Living Docs as a **dev self-test** signal — it tells QC the
+> dev ran their checks; it is NOT a statement of official test coverage.
 
 ## Gate
 {{include:steps/gate.md}}
@@ -170,12 +176,32 @@ xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhon
 
 ---
 
+## Write Trace State
+
+After the run, persist results to the **authoritative TSV** in the service so they reach
+the Living Docs report at the spec module (via `/sync` + `/validate-traces`). The test
+files themselves stay in the service — only the run *status* is reported.
+
+Update `{paths.trace_dir}/{UC-ID}.tsv` — for each scenario row (matched by `sc_id` via its
+test's `@trace.verifies={UC-ID}-SC{N}` tag):
+
+| Column | Value |
+|--------|-------|
+| `dev_selftest` | `pass` if all tests for this SC passed · `fail` if any failed · `not_run` if its tests were skipped/absent |
+| `dev_selftest_at` | today `YYYY-MM-DD` |
+
+Leave all other columns unchanged. `dev_selftest`/`dev_selftest_at` are orthogonal to `status`
+(OK/GAP/DRIFT/UNTRACKED): `status` tracks *coverage*, `dev_selftest` tracks the latest *run result*.
+
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
+
 ## Output
 
 {{include:steps/report-footer.md}}
 
 ```
-/run-tests Report — {UC-ID} ({active_module})
+/dev-run-test Report — {UC-ID} ({active_module})
 ✅ Passed: {N} | ❌ Failed: {M} | ⏭️ Skipped: {K} | Duration: {X}s
 
 ## Failed Tests
@@ -185,7 +211,11 @@ xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhon
 ## Recommendations
 {specific fix per failure}
 
+Trace: {paths.trace_dir}/{UC-ID}.tsv updated (dev_selftest, dev_selftest_at)
+
 Next:
   All tests pass → /review-code {UC-ID}
   Tests fail     → /fix-bug {TICKET_ID} (real bug) or fix test (wrong expectation)
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```