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

package/commands/validate-traces.md

@@ -165,7 +165,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`)
@@ -177,13 +177,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.
 
 ---
 
@@ -207,7 +208,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).
@@ -300,7 +301,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).
 
 ---
 
@@ -375,8 +376,12 @@ Check whether `services` array exists in `project-context.yaml`.
   - Use `services[N].trace_dir` if explicitly set
   - Otherwise default to `{services[N].path}/.trace`
 - Set `all_trace_dirs = [ dir1, dir2, ... ]` — one per service
-- Set `umbrella_root_trace = ".trace"` (at umbrella workspace root)
 - Step 1 will read TSVs from ALL dirs in `all_trace_dirs`, tagged by service name
+- **Resolve the Living Docs home (canonical report location):**
+  - If `setup.spec_source` is set → `living_docs_dir = {spec_source}/.living-docs`
+    *(the shared specs module — mounted inside every service/umbrella workspace, so the panel resolves it no matter which submodule the dev is standing in)*
+  - Else (umbrella without a separate spec repo) → `living_docs_dir = .living-docs` at umbrella root
+- **Resolve the panel mirror:** `panel_mirror = ./.trace` at the **current workspace root** (wherever this command runs). The VS Code panel reads `.trace/trace-report.json` from the open workspace — writing the merged report here is what makes the view non-empty when a dev opens a service submodule directly.
 
 **If no `services` key (single-service mode):**
 - Set `all_trace_dirs = [ {paths.trace_dir} ]`
@@ -439,6 +444,7 @@ If code was generated from an older revision → flag `TECHDOC_DRIFT`.
 *Skip this step if no TSV files existed (handled by Step 1 no-TSV path).*
 
 For each `.tsv` file processed: write updated `spec_ver`, `status`, `last_updated` back to disk.
+Do **not** modify `dev_selftest` or `dev_selftest_at` — those are owned by `/dev-run-test`; this command only reads them for the report.
 
 ### Step 7 — Compute dashboard aggregates
 
@@ -454,6 +460,11 @@ test_coverage    = rows where test_count > 0 / total_scs
 drift_count      = rows where status == DRIFT
 untracked_count  = rows where status == UNTRACKED
 gap_count        = rows where status == GAP
+dev_selftest_passing = rows where dev_selftest == pass
+dev_selftest_failing = rows where dev_selftest == fail
+dev_selftest_not_run = rows where dev_selftest in (not_run, —)
+# NOTE: this is the DEV self-check signal (did the dev run their own smoke tests),
+# NOT official QC/dev-team coverage — keep it labeled as such on the dashboard.
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/
 ```
 
@@ -481,6 +492,9 @@ Schema:
     "drift_count": 0,
     "gap_count": 0,
     "untracked_count": 0,
+    "dev_selftest_passing": 0,
+    "dev_selftest_failing": 0,
+    "dev_selftest_not_run": 0,
     "tech_docs_count": 0
   },
   "prds": [
@@ -506,6 +520,8 @@ Schema:
               "implemented_by": "<ClassName.method or null>",
               "test_count": 0,
               "test_classes": ["<TestClass1>", "<TestClass2>"],
+              "dev_selftest": "pass | fail | not_run",
+              "dev_selftest_at": "<YYYY-MM-DD or null>",
               "prd_version": "<prd version when BDD was generated>",
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
@@ -532,7 +548,7 @@ Schema:
         "sc_id": "<SC-ID>",
         "sc_title": "<title>",
         "implemented_by": "<method>",
-        "fix": "/generate-tests <UC-ID>"
+        "fix": "/dev-gen-test <UC-ID>"
       }
     ],
     "untracked": [
@@ -570,37 +586,40 @@ Schema:
 - `tech_doc_revision`: use integer; `0` if not yet generated
 - `code_coverage_pct` / `test_coverage_pct`: round to nearest integer (0–100)
 - Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
-- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`
+- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`
 
-### Step 8b — Umbrella Living Docs Sync *(umbrella mode only)*
+### Step 8b — Living Docs Sync *(umbrella mode only)*
 
 *Skip this step in single-service mode.*
 
-After writing each service's `trace-report.json`, sync trace files to the umbrella root so the Living Docs VS Code panel (opened at umbrella root) can read them:
+Authoritative trace state stays in each service submodule's `.trace/` (committed there).
+This step publishes the merged report to the **canonical Living Docs home** (the specs
+module) and drops a local mirror so the panel is never empty.
 
-1. Create directory `{umbrella_root_trace}/` if it does not exist (`mkdir -p .trace`).
+1. **Write canonical merged report** to `{living_docs_dir}/` (`mkdir -p` it first):
+   - `{living_docs_dir}/trace-report.json` — merge every per-service `trace-report.json`
+     into one document, add a `"service"` field per scenario row, recalc summary aggregates.
+   - `{living_docs_dir}/{service-name}/{UC-ID}.tsv` — copy each service's TSVs, namespaced
+     by service. Overwrite; don't delete TSVs whose service source is gone (prior runs).
 
-2. **Copy TSV files** from each service trace dir to umbrella trace dir with service namespace:
-   ```
-   {service.path}/.trace/{UC-ID}.tsv  →  .trace/{service-name}/{UC-ID}.tsv
-   ```
-   Overwrite if exists. Do not delete files in `.trace/` that no longer have a service source — they may be from a previous run.
-
-3. **Write aggregated `trace-report.json`** to `{umbrella_root_trace}/trace-report.json`:
-   - Merge all per-service `trace-report.json` data into one document
-   - Add `"service"` field to each scenario row
-   - Recalculate summary aggregates across all services
+2. **Mirror to the panel location** `{panel_mirror}` (`./.trace` at the current workspace
+   root) so a dev who opened *this* repo (umbrella **or** a single service submodule) sees
+   data immediately: copy `{living_docs_dir}/trace-report.json` → `{panel_mirror}/trace-report.json`
+   (and the namespaced TSVs). If `panel_mirror` already resolves to `living_docs_dir`, skip.
 
-4. **Print sync summary:**
+3. **Print sync summary:**
    ```
-   Umbrella sync → .trace/
-     user-service  : {N} TSV files copied
-     order-service : {N} TSV files copied
+   Living Docs → {living_docs_dir}/  (canonical, in specs module)
+     user-service  : {N} TSV files
+     order-service : {N} TSV files
      trace-report.json: merged ({total} scenarios across {S} services)
-   Living Docs panel will reflect this data immediately.
+   Panel mirror → {panel_mirror}/trace-report.json  (current workspace)
    ```
 
-> **Note:** `.trace/` at umbrella root is a **read-only mirror** — do NOT commit it to the umbrella repo. Add `.trace/` to the umbrella's `.gitignore`. Authoritative trace state lives in each service submodule's `.trace/` dir and is committed there.
+> **Note — both locations are generated, gitignored mirrors.** Add `.living-docs/` to the
+> **specs module's** `.gitignore` and `.trace/` to the current repo's `.gitignore`. The only
+> committed, authoritative trace state is each service submodule's own `.trace/`. The report
+> is regenerated by `/validate-traces` or `/sync` — never commit it.
 
 ## Output
 
@@ -642,13 +661,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}` |
@@ -701,11 +720,12 @@ Tech-Doc Revision Drift:
 
 Recommendations:
   - /generate-code {UC-ID}      for DRIFT and UNTRACKED scenarios
-  - /generate-tests {UC-ID}     for GAP (missing tests)
+  - /dev-gen-test {UC-ID}     for GAP (missing tests)
   - /generate-bdd {prd-file}    for PRD version drift
 
 [Umbrella mode only]
-Living Docs synced → .trace/ (umbrella root)
-  Tip: run /validate-traces after each codegen session to refresh the panel.
-  .trace/ at umbrella root is a mirror — do not commit it (add to .gitignore).
+Living Docs canonical → {living_docs_dir}/  (specs module — shared, gitignored)
+Panel mirror          → {panel_mirror}/trace-report.json  (current workspace)
+  Tip: run /validate-traces (or /sync) after each codegen session to refresh the panel.
+  Both are generated mirrors — do not commit (.living-docs/ + .trace/ in .gitignore).
 ```

package/commands/validate-traces.tmpl

@@ -23,8 +23,12 @@ Check whether `services` array exists in `project-context.yaml`.
   - Use `services[N].trace_dir` if explicitly set
   - Otherwise default to `{services[N].path}/.trace`
 - Set `all_trace_dirs = [ dir1, dir2, ... ]` — one per service
-- Set `umbrella_root_trace = ".trace"` (at umbrella workspace root)
 - Step 1 will read TSVs from ALL dirs in `all_trace_dirs`, tagged by service name
+- **Resolve the Living Docs home (canonical report location):**
+  - If `setup.spec_source` is set → `living_docs_dir = {spec_source}/.living-docs`
+    *(the shared specs module — mounted inside every service/umbrella workspace, so the panel resolves it no matter which submodule the dev is standing in)*
+  - Else (umbrella without a separate spec repo) → `living_docs_dir = .living-docs` at umbrella root
+- **Resolve the panel mirror:** `panel_mirror = ./.trace` at the **current workspace root** (wherever this command runs). The VS Code panel reads `.trace/trace-report.json` from the open workspace — writing the merged report here is what makes the view non-empty when a dev opens a service submodule directly.
 
 **If no `services` key (single-service mode):**
 - Set `all_trace_dirs = [ {paths.trace_dir} ]`
@@ -87,6 +91,7 @@ If code was generated from an older revision → flag `TECHDOC_DRIFT`.
 *Skip this step if no TSV files existed (handled by Step 1 no-TSV path).*
 
 For each `.tsv` file processed: write updated `spec_ver`, `status`, `last_updated` back to disk.
+Do **not** modify `dev_selftest` or `dev_selftest_at` — those are owned by `/dev-run-test`; this command only reads them for the report.
 
 ### Step 7 — Compute dashboard aggregates
 
@@ -102,6 +107,11 @@ test_coverage    = rows where test_count > 0 / total_scs
 drift_count      = rows where status == DRIFT
 untracked_count  = rows where status == UNTRACKED
 gap_count        = rows where status == GAP
+dev_selftest_passing = rows where dev_selftest == pass
+dev_selftest_failing = rows where dev_selftest == fail
+dev_selftest_not_run = rows where dev_selftest in (not_run, —)
+# NOTE: this is the DEV self-check signal (did the dev run their own smoke tests),
+# NOT official QC/dev-team coverage — keep it labeled as such on the dashboard.
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/
 ```
 
@@ -129,6 +139,9 @@ Schema:
     "drift_count": 0,
     "gap_count": 0,
     "untracked_count": 0,
+    "dev_selftest_passing": 0,
+    "dev_selftest_failing": 0,
+    "dev_selftest_not_run": 0,
     "tech_docs_count": 0
   },
   "prds": [
@@ -154,6 +167,8 @@ Schema:
               "implemented_by": "<ClassName.method or null>",
               "test_count": 0,
               "test_classes": ["<TestClass1>", "<TestClass2>"],
+              "dev_selftest": "pass | fail | not_run",
+              "dev_selftest_at": "<YYYY-MM-DD or null>",
               "prd_version": "<prd version when BDD was generated>",
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
@@ -180,7 +195,7 @@ Schema:
         "sc_id": "<SC-ID>",
         "sc_title": "<title>",
         "implemented_by": "<method>",
-        "fix": "/generate-tests <UC-ID>"
+        "fix": "/dev-gen-test <UC-ID>"
       }
     ],
     "untracked": [
@@ -218,37 +233,40 @@ Schema:
 - `tech_doc_revision`: use integer; `0` if not yet generated
 - `code_coverage_pct` / `test_coverage_pct`: round to nearest integer (0–100)
 - Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
-- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`
+- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`
 
-### Step 8b — Umbrella Living Docs Sync *(umbrella mode only)*
+### Step 8b — Living Docs Sync *(umbrella mode only)*
 
 *Skip this step in single-service mode.*
 
-After writing each service's `trace-report.json`, sync trace files to the umbrella root so the Living Docs VS Code panel (opened at umbrella root) can read them:
+Authoritative trace state stays in each service submodule's `.trace/` (committed there).
+This step publishes the merged report to the **canonical Living Docs home** (the specs
+module) and drops a local mirror so the panel is never empty.
 
-1. Create directory `{umbrella_root_trace}/` if it does not exist (`mkdir -p .trace`).
+1. **Write canonical merged report** to `{living_docs_dir}/` (`mkdir -p` it first):
+   - `{living_docs_dir}/trace-report.json` — merge every per-service `trace-report.json`
+     into one document, add a `"service"` field per scenario row, recalc summary aggregates.
+   - `{living_docs_dir}/{service-name}/{UC-ID}.tsv` — copy each service's TSVs, namespaced
+     by service. Overwrite; don't delete TSVs whose service source is gone (prior runs).
 
-2. **Copy TSV files** from each service trace dir to umbrella trace dir with service namespace:
-   ```
-   {service.path}/.trace/{UC-ID}.tsv  →  .trace/{service-name}/{UC-ID}.tsv
-   ```
-   Overwrite if exists. Do not delete files in `.trace/` that no longer have a service source — they may be from a previous run.
-
-3. **Write aggregated `trace-report.json`** to `{umbrella_root_trace}/trace-report.json`:
-   - Merge all per-service `trace-report.json` data into one document
-   - Add `"service"` field to each scenario row
-   - Recalculate summary aggregates across all services
+2. **Mirror to the panel location** `{panel_mirror}` (`./.trace` at the current workspace
+   root) so a dev who opened *this* repo (umbrella **or** a single service submodule) sees
+   data immediately: copy `{living_docs_dir}/trace-report.json` → `{panel_mirror}/trace-report.json`
+   (and the namespaced TSVs). If `panel_mirror` already resolves to `living_docs_dir`, skip.
 
-4. **Print sync summary:**
+3. **Print sync summary:**
    ```
-   Umbrella sync → .trace/
-     user-service  : {N} TSV files copied
-     order-service : {N} TSV files copied
+   Living Docs → {living_docs_dir}/  (canonical, in specs module)
+     user-service  : {N} TSV files
+     order-service : {N} TSV files
      trace-report.json: merged ({total} scenarios across {S} services)
-   Living Docs panel will reflect this data immediately.
+   Panel mirror → {panel_mirror}/trace-report.json  (current workspace)
    ```
 
-> **Note:** `.trace/` at umbrella root is a **read-only mirror** — do NOT commit it to the umbrella repo. Add `.trace/` to the umbrella's `.gitignore`. Authoritative trace state lives in each service submodule's `.trace/` dir and is committed there.
+> **Note — both locations are generated, gitignored mirrors.** Add `.living-docs/` to the
+> **specs module's** `.gitignore` and `.trace/` to the current repo's `.gitignore`. The only
+> committed, authoritative trace state is each service submodule's own `.trace/`. The report
+> is regenerated by `/validate-traces` or `/sync` — never commit it.
 
 ## Output
 
@@ -289,11 +307,12 @@ Tech-Doc Revision Drift:
 
 Recommendations:
   - /generate-code {UC-ID}      for DRIFT and UNTRACKED scenarios
-  - /generate-tests {UC-ID}     for GAP (missing tests)
+  - /dev-gen-test {UC-ID}     for GAP (missing tests)
   - /generate-bdd {prd-file}    for PRD version drift
 
 [Umbrella mode only]
-Living Docs synced → .trace/ (umbrella root)
-  Tip: run /validate-traces after each codegen session to refresh the panel.
-  .trace/ at umbrella root is a mirror — do not commit it (add to .gitignore).
+Living Docs canonical → {living_docs_dir}/  (specs module — shared, gitignored)
+Panel mirror          → {panel_mirror}/trace-report.json  (current workspace)
+  Tip: run /validate-traces (or /sync) after each codegen session to refresh the panel.
+  Both are generated mirrors — do not commit (.living-docs/ + .trace/ in .gitignore).
 ```

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.1
+0.10.0

package/core/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/core/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/core/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.
 ```