@edupia-tutor/spec-driven-docs 0.14.0

package/commands/validate-traces.tmpl

@@ -0,0 +1,348 @@
+# /validate-traces — Traceability Coverage Matrix
+
+Read-only check of coverage between specs, code, and tests — including PRD version drift.
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a domain name or specific UC-ID from `$ARGUMENTS`. There is no single file to resolve — the command scans multiple directories.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Process
+
+### Step 0 — Umbrella Mode Detection
+
+Check whether `services` array exists in `project-context.yaml`.
+
+**If `services` exists (umbrella mode):**
+- Resolve the trace dir(s):
+  - **If `setup.spec_source` is set (consolidated trace):** `all_trace_dirs = [ {spec_source}/.trace ]` — a **single** authoritative location in the spec repo. Scenarios carry their owning service via the `@trace.service` field, so no per-service split is needed. This is the common case.
+  - **Else (no spec_source — legacy per-service trace):** one dir per service — `services[N].trace_dir` if set, else `{services[N].path}/.trace`; `all_trace_dirs = [ dir1, dir2, … ]`, tagged by service name on read.
+- Step 1 reads TSVs from `all_trace_dirs`.
+- **Resolve the Living Docs home (generated 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 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} ]`
+- No umbrella sync needed
+
+---
+
+### Step 1 — Load TSV data
+
+**Umbrella mode:** read all `{trace_dir}/**/*.tsv` files from every dir in `all_trace_dirs`. For each TSV, tag its rows with the originating service name.
+
+**Single-service mode:** read all `{paths.trace_dir}/{domain}/**/*.tsv` files matching the target domain (or `{paths.trace_dir}/**/*.tsv` for all domains if no domain filter).
+
+Each file gives the persisted trace state for that UC.
+
+**If no `.tsv` files found** in any of the trace dirs:
+- Scan all `{paths.specs_dir}/**/*.feature` files in the target domain to build an in-memory list of all scenarios.
+- Treat all scenarios as `UNTRACKED` (no code generated yet).
+- Print: "⚠️ No trace files found. All {N} scenarios across {M} UCs are UNTRACKED."
+- Suggest: "Run `/generate-bdd {prd-file}` to initialize trace state, or `/generate-code {feature-file}` to generate code."
+- **Skip Steps 2–6 entirely.** Proceed directly to Step 7 using this in-memory state — do NOT abort.
+
+### Step 2 — Reconcile with current `.feature` files
+
+For each `.tsv` row, read the corresponding `.feature` file and get the **current** `@trace.sc_version` for that SC.
+If the `.feature` SC version differs from the `.tsv` `spec_ver` → update `spec_ver` in memory (will be written back).
+
+Also detect SCs present in `.feature` but missing from `.tsv` → add as new rows with `status: UNTRACKED`.
+
+### Step 3 — Compute `status` per scenario
+
+Apply rules in priority order:
+
+| Rule | Status | Condition |
+|------|--------|-----------|
+| 1 | `UNTRACKED` | `implemented_by == —` (no code generated yet) |
+| 2 | `GAP` | `implemented_by != —` AND (`test_count == —` OR `test_count == 0`) |
+| 3 | `DRIFT` | `spec_ver != gen_ver` (scenario updated since last codegen) |
+| 4 | `OK` | all of: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
+
+### Step 4 — PRD version drift check
+
+For each UC, compare:
+- Current PRD `| **Version** |` from `{paths.specs_dir}/{domain}/{prd-slug}/prd.md`
+- `prd_version` stored in `.tsv` (version at time of BDD generation)
+- `@trace.prd_version` in the code files implementing that UC
+
+If any layer is behind current PRD version → flag `PRD_DRIFT` and extract changelog entries since that version.
+
+### Step 5 — Tech-doc revision drift check
+
+For each UC that has a tech-doc, compare the stored revision against the current doc — for **both** tech-doc kinds:
+
+- **BE contract:** `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` vs `tech_doc_revision` in `.tsv`.
+  Code generated from an older revision → flag `TECHDOC_DRIFT`.
+- **FE tech-design:** `@trace.revision` in `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` vs `fe_tech_doc_revision` in `.tsv` (per platform row).
+  FE code generated from an older revision → flag `FE_TECHDOC_DRIFT`.
+
+Skip whichever kind has no doc / no stored revision (`—`).
+
+### Step 6 — Write status back to TSV
+
+*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`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (owned by `/qc-run-test` + `/report-bug`); this command only reads them for the report.
+
+### Step 7 — Compute dashboard aggregates
+
+```
+total_prds       = count distinct PRD files in {paths.specs_dir}/{domain}/*/prd.md
+approved_prds    = PRDs with | Status | approved
+total_ucs        = count distinct UC-IDs across all .tsv files
+approved_ucs     = UCs with uc_status == approved
+draft_ucs        = UCs with uc_status == draft
+total_scs        = total rows across all .tsv files
+code_coverage    = rows where implemented_by != — / total_scs
+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: dev_selftest is the DEV self-check signal (did the dev run their own smoke tests),
+# NOT official coverage — keep it labeled as such on the dashboard.
+qc_passing       = rows where qc_status == pass
+qc_failing       = rows where qc_status == fail
+qc_skipped       = rows where qc_status == skip
+qc_not_run       = rows where qc_status in (not_run, —)
+# qc_status is the OFFICIAL QC automation result (set by /qc-run-test),
+# shown alongside — never merged with — dev_selftest.
+waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
+waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify
+# qc_owner + qc_blocked_by answer "case nào đang chờ ai" — surface as a "Waiting on" column.
+tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/*/tech-docs/
+```
+
+### Step 8 — Write JSON report
+
+Write `{paths.trace_dir}/trace-report.json` (overwrite if exists). This file is the single source of truth for web dashboards — it contains the full snapshot at the time `/validate-traces` was last run.
+
+Schema:
+
+```json
+{
+  "generated_at": "<ISO-8601 timestamp>",
+  "domain": "<domain argument, or 'all' if no filter>",
+  "summary": {
+    "total_prds": 0,
+    "approved_prds": 0,
+    "total_ucs": 0,
+    "approved_ucs": 0,
+    "draft_ucs": 0,
+    "total_scs": 0,
+    "coded_scs": 0,
+    "tested_scs": 0,
+    "code_coverage_pct": 0,
+    "test_coverage_pct": 0,
+    "drift_count": 0,
+    "gap_count": 0,
+    "untracked_count": 0,
+    "dev_selftest_passing": 0,
+    "dev_selftest_failing": 0,
+    "dev_selftest_not_run": 0,
+    "qc_passing": 0,
+    "qc_failing": 0,
+    "qc_skipped": 0,
+    "qc_not_run": 0,
+    "waiting_dev": 0,
+    "waiting_po": 0,
+    "tech_docs_count": 0
+  },
+  "prds": [
+    {
+      "prd_id": "<e.g. PAY>",
+      "prd_status": "approved | draft | other",
+      "total_scs": 0,
+      "coded_scs": 0,
+      "tested_scs": 0,
+      "drift_count": 0,
+      "gap_count": 0,
+      "untracked_count": 0,
+      "ucs": [
+        {
+          "uc_id": "<e.g. PAY-UC01>",
+          "uc_status": "approved | draft | other",
+          "scenarios": [
+            {
+              "sc_id": "<e.g. PAY-UC01-SC1>",
+              "sc_title": "<title>",
+              "spec_ver": "<current version from .feature>",
+              "gen_ver": "<version at codegen time>",
+              "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>",
+              "qc_status": "pass | fail | skip | not_run",
+              "qc_run_at": "<YYYY-MM-DD or null>",
+              "qc_owner": "dev | po | null",
+              "qc_blocked_by": "<BUG-id / GAP-id or null>",
+              "prd_version": "<prd version when BDD was generated>",
+              "bdd_version": "<bdd version when code was generated>",
+              "tech_doc_revision": 0,
+              "fe_tech_doc_revision": 0,
+              "status": "OK | DRIFT | GAP | UNTRACKED",
+              "last_updated": "<YYYY-MM-DD>"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "issues": {
+    "drift": [
+      {
+        "sc_id": "<SC-ID>",
+        "sc_title": "<title>",
+        "spec_ver": "<current>",
+        "gen_ver": "<at codegen>",
+        "fix": "/generate-code <UC-ID>"
+      }
+    ],
+    "gap": [
+      {
+        "sc_id": "<SC-ID>",
+        "sc_title": "<title>",
+        "implemented_by": "<method>",
+        "fix": "/dev-gen-test <UC-ID>"
+      }
+    ],
+    "untracked": [
+      {
+        "sc_id": "<SC-ID>",
+        "sc_title": "<title>",
+        "fix": "/generate-code <UC-ID>"
+      }
+    ],
+    "prd_version_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "code_prd_version": "<version in code tag>",
+        "current_prd_version": "<version in PRD file>",
+        "changelog_since": ["<v1.1: ...>", "<v1.2: ...>"],
+        "fix": "/generate-bdd <prd-file> then /generate-code <UC-ID>"
+      }
+    ],
+    "techdoc_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "code_revision": 0,
+        "current_revision": 0,
+        "fix": "/generate-code <UC-ID>"
+      }
+    ],
+    "fe_techdoc_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app",
+        "code_revision": 0,
+        "current_revision": 0,
+        "fix": "/generate-code <UC-ID> --phase=integration"
+      }
+    ]
+  }
+}
+```
+
+**Rules:**
+- `implemented_by`: use `null` (not `"—"`) in JSON when no value
+- `test_count`: use integer `0` (not `"—"`) when no tests
+- `test_classes`: use `[]` (not `"—"`) when no test classes
+- `tech_doc_revision` / `fe_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`; `fe_tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
+- **Backward-compat:** older TSVs may be missing newer columns from the header — treat any absent column as its empty value (do not error): `qc_owner`/`qc_blocked_by` (pre-19-col) → `null`; `fe_tech_doc_revision` (pre-22-col) → `0`. The next `/generate-bdd` re-gen upgrades the header to the current 22-column layout.
+
+### Step 8b — Living Docs Sync *(umbrella mode only)*
+
+*Skip this step in single-service mode.*
+
+**With `spec_source` set,** the authoritative trace TSVs already live in **one** place —
+`{spec_source}/.trace/` (committed in the spec repo). There is **no per-service merge**:
+each scenario row carries its owning service via `@trace.service`. This step just
+(re)generates the report and refreshes the local panel.
+
+1. **Write the report** to `{living_docs_dir}/trace-report.json` (`mkdir -p` first) — built
+   directly from `{spec_source}/.trace/*.tsv`, with a `"service"` field per scenario row and
+   the summary aggregates. *(Legacy no-`spec_source` umbrellas still merge every per-service
+   `trace-report.json` into one document, namespaced by service.)*
+
+2. **Mirror to the panel location** `{panel_mirror}` (`./.trace` at the current workspace
+   root) so a dev who opened *this* repo sees data immediately: copy
+   `{living_docs_dir}/trace-report.json` (+ the `{UC-ID}.tsv` files) → `{panel_mirror}/`.
+   If `panel_mirror` already resolves to `{spec_source}/.trace`, skip.
+
+3. **Print sync summary:**
+   ```
+   Living Docs → {living_docs_dir}/trace-report.json  ({total} scenarios across {S} services)
+   Trace (authoritative) → {spec_source}/.trace/   (committed in spec repo)
+   Panel mirror → {panel_mirror}/trace-report.json  (current workspace)
+   ```
+
+> **Note:** the committed, authoritative trace state is `{spec_source}/.trace/*.tsv` (in the
+> spec repo — one place for the PM). The report (`.living-docs/`) and the panel mirror
+> (`./.trace` at a workspace that is not the spec repo) are **generated** — gitignore them;
+> they are regenerated by `/validate-traces` or `/sync`.
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/validate-traces — {domain}
+
+📄 {paths.trace_dir}/trace-report.json  ← updated
+
+┌─────────────────────────────────────────────────────────────────────────────────────┐
+│  PRDs      Use Cases     Scenarios   Code Cov.  Test Cov.  Drift  Untracked  Gap   │
+│  {N}       {N}           {N}         {N}%       {N}%       {N}    {N}        {N}   │
+│  {A} appr  {A} appr                 {X}/{T} SCs {X}/{T} SCs                        │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+
+| UC-ID       | SC   | Title (truncated)            | Spec  | Gen   | Code                 | Tests          | Status   |
+|-------------|------|------------------------------|-------|-------|----------------------|----------------|----------|
+| {UC}-UC1    | SC1  | {title...}                   | v1.0  | v1.0  | ✅ {Controller.fn}   | ✅ 10 tests    | OK       |
+| {UC}-UC1    | SC2  | {title...}                   | v1.1  | v1.0  | ✅ {Controller.fn}   | ✅ 3 tests     | DRIFT    |
+| {UC}-UC1    | SC6  | {title...}                   | v1.0  | —     | —                    | —              | UNTRACKED|
+| {UC}-UC2    | SC1  | {title...}                   | v1.0  | v1.0  | ✅ {Controller.fn}   | —              | GAP      |
+
+Drift Detail:
+  {UC}-UC1-SC2 — spec v1.1 but code generated from v1.0
+    → Re-run: /generate-code {UC-ID}
+
+PRD Version Drift:
+  {UC}-UC2 — code at PRD v1.0, PRD now at v1.2
+    Changes since v1.0:
+      v1.1: {changelog entry}
+      v1.2: {changelog entry}
+    → /generate-bdd {prd-file} then /generate-code {UC-ID}
+
+Tech-Doc Revision Drift:
+  {UC}-UC3 — code generated from tech-doc revision 2, now at revision 4
+    → Review tech-doc changes then /generate-code {UC-ID}
+
+Recommendations:
+  - /generate-code {UC-ID}      for DRIFT and UNTRACKED scenarios
+  - /dev-gen-test {UC-ID}     for GAP (missing tests)
+  - /generate-bdd {prd-file}    for PRD version drift
+
+[Umbrella mode only]
+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

@@ -0,0 +1 @@
+0.14.0