@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/bin/trace-schema.json

@@ -0,0 +1,1199 @@
+{
+  "$comment": [
+    "NGUỒN-SỰ-THẬT MÁY ĐỌC cho contract trace của framework. bin/self-check.js đối chiếu",
+    "file này với commands/*.tmpl + steps/*.md mỗi lần `npm run build`, và FAIL build khi lệch.",
+    "",
+    "Vì sao tồn tại: 19/23 GAP trong GAPS.md là cùng một lỗi — contract được phát biểu lại",
+    "bằng prose ở nhiều lệnh rồi lệch nhau qua từng lần sửa. Ca thuần khiết nhất là",
+    "@trace.sc_version: 3 consumer, 0 producer, tồn tại qua nhiều version mà không lệnh nào,",
+    "không cổng nào, không test nào phát hiện. Rule R1 dưới đây bắt đúng lớp lỗi đó.",
+    "",
+    "ĐỔI CONTRACT: sửa file này TRƯỚC, rồi mới sửa lệnh. Build fail nếu lệnh lệch schema.",
+    "Bản dành cho người đọc: docs/04-reference/trace-schema.md (giữ đồng bộ với file này).",
+    "",
+    "Định dạng JSON chứ không YAML vì package.json có ZERO dependency (npx chạy không cần",
+    "install) — thêm js-yaml chỉ để đọc một file cấu hình build-time là không đáng."
+  ],
+  "actors": {
+    "$comment": "Tên logic → file nguồn. self-check tìm chuỗi field trong các file này.",
+    "generate-bdd": "commands/generate-bdd.tmpl",
+    "generate-code": "commands/generate-code.tmpl",
+    "generate-tech-docs": "commands/generate-tech-docs.tmpl",
+    "generate-prd": "commands/generate-prd.tmpl",
+    "generate-design-spec": "commands/generate-design-spec.tmpl",
+    "review-context": "commands/review-context.tmpl",
+    "review-tech-docs": "commands/review-tech-docs.tmpl",
+    "review-code": "commands/review-code.tmpl",
+    "validate-traces": "commands/validate-traces.tmpl",
+    "dev-gen-test": "commands/dev-gen-test.tmpl",
+    "dev-run-test": "commands/dev-run-test.tmpl",
+    "dev-smoke-test": "commands/dev-smoke-test.tmpl",
+    "qc-run-test": "commands/qc-run-test.tmpl",
+    "report-bug": "commands/report-bug.tmpl",
+    "propose-scenario": "commands/propose-scenario.tmpl",
+    "fix-bug": "commands/fix-bug.tmpl",
+    "refine-prd": "commands/refine-prd.tmpl",
+    "extend-prd": "commands/extend-prd.tmpl",
+    "sync": "commands/sync.tmpl",
+    "setup-ai-first": "commands/setup-ai-first.tmpl",
+    "generate-spec-manifest": "commands/generate-spec-manifest.tmpl",
+    "qc-analyze": "commands/qc-analyze.tmpl",
+    "qc-design-test": "commands/qc-design-test.tmpl",
+    "map-testids": "commands/map-testids.tmpl",
+    "debug": "commands/debug.tmpl",
+    "design-spec-template": "templates/design-spec.template.md",
+    "context-loader": "steps/context-loader.md",
+    "gate": "steps/gate.md",
+    "report-footer": "steps/report-footer.md",
+    "feature-template": "templates/feature.template",
+    "prd-template": "templates/prd.template.md",
+    "tech-design-template": "templates/tech-design.template.md"
+  },
+  "tags": [
+    {
+      "name": "@trace.sc_version",
+      "artifact": ".feature",
+      "scope": "scenario",
+      "shape": "semver-lite (1.0, 1.1)",
+      "written_by": [
+        "generate-bdd",
+        "feature-template"
+      ],
+      "bumped_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "why": "Tín hiệu DUY NHẤT cho DRIFT (spec_ver != gen_ver). Không có producer = DRIFT chết."
+    },
+    {
+      "name": "@trace.bdd_version",
+      "artifact": ".feature",
+      "scope": "file",
+      "shape": "semver-lite scalar",
+      "written_by": [
+        "generate-bdd",
+        "feature-template"
+      ],
+      "bumped_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "generate-code",
+        "generate-tech-docs",
+        "validate-traces",
+        "review-tech-docs",
+        "review-context"
+      ],
+      "why": "Drift cấp file (Background/dataset/business-definition) mà sc_version không thấy."
+    },
+    {
+      "name": "@trace.bdd_versions",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "shape": "map theo platform (system=1.5, web=1.9)",
+      "written_by": [
+        "generate-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "validate-traces",
+        "review-tech-docs"
+      ],
+      "why": "Số NHIỀU, cố ý khác @trace.bdd_version (scalar) — cùng tên cho hai kiểu dữ liệu làm vỡ parser generic."
+    },
+    {
+      "name": "@trace.platform",
+      "artifact": ".feature",
+      "scope": "file",
+      "required": "always",
+      "values_from": "platform",
+      "written_by": [
+        "generate-bdd",
+        "feature-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "generate-tech-docs",
+        "review-context",
+        "context-loader"
+      ],
+      "why": "Quyết BE/FE ở generate-code (cấm fallback platform_type) + tên sổ trace + lookup design-spec. Lưu ý: validate-traces và report-bug KHÔNG đọc tag này — chúng suy platform từ TÊN FILE .tsv ({UC-ID}-{platform}.tsv), nên không phải consumer của tag."
+    },
+    {
+      "name": "@trace.prd_version",
+      "artifact": ".feature + code",
+      "scope": "file + method",
+      "written_by": [
+        "generate-bdd",
+        "generate-code",
+        "feature-template"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "why": "Nguồn của PRD_DRIFT (validate-traces Step 4 so 3 tầng: PRD file, TSV, tag trong code)."
+    },
+    {
+      "name": "@trace.implements",
+      "artifact": "code",
+      "scope": "method",
+      "shape": "{UC-ID}-SC{N}",
+      "written_by": [
+        "generate-code",
+        "setup-ai-first"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code",
+        "dev-gen-test",
+        "dev-smoke-test",
+        "fix-bug"
+      ],
+      "why": "Khoá chính của trace ở tầng code. Tra bằng khớp chuỗi CHÍNH XÁC → cấm trỏ thư mục."
+    },
+    {
+      "name": "@trace.source",
+      "artifact": "code",
+      "scope": "method",
+      "shape": "{specs_dir}/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature",
+      "written_by": [
+        "generate-code",
+        "setup-ai-first"
+      ],
+      "read_by": [
+        "review-code"
+      ],
+      "why": "Con trỏ ngược về spec. PHẢI gồm segment {platform}."
+    },
+    {
+      "name": "@trace.tech_doc_revision",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "review-code"
+      ],
+      "why": "Ghi revision tech-doc mà method này được sinh theo. BẤT ĐỐI XỨNG ĐÃ BIẾT: validate-traces Step 5 tính TECHDOC_DRIFT từ cột TSV tech_doc_revision chứ không từ tag này (khác Step 4, có so tag @trace.prd_version trong code). Nên hiện chỉ review-code kiểm sự CÓ MẶT của nó. Muốn đối xứng thì Step 5 phải đọc thêm tag trong code."
+    },
+    {
+      "name": "@trace.verifies",
+      "artifact": "test",
+      "scope": "method",
+      "shape": "{UC-ID}-SC{N}",
+      "written_by": [
+        "dev-gen-test",
+        "qc-run-test",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code",
+        "dev-run-test",
+        "qc-run-test"
+      ],
+      "why": "Khớp test → sc_id khi ghi test_count/dev_selftest/qc_status."
+    },
+    {
+      "name": "@trace.scenario",
+      "artifact": ".feature",
+      "scope": "scenario",
+      "shape": "{UC-ID}-SC{N}",
+      "written_by": [
+        "generate-bdd",
+        "propose-scenario",
+        "feature-template"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "why": "Sinh sc_id cho row TSV. Thiếu nó = scenario vô hình với toàn bộ coverage."
+    },
+    {
+      "name": "@trace.status",
+      "artifact": ".feature + tech-design.md",
+      "scope": "file",
+      "values_from": "approval_status",
+      "written_by": [
+        "feature-template",
+        "review-context",
+        "review-tech-docs",
+        "generate-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "validate-traces",
+        "review-tech-docs"
+      ],
+      "why": "Cổng duyệt: DS1 của generate-code, và uc_status sync từ đây."
+    },
+    {
+      "name": "@trace.revision",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "shape": "integer",
+      "written_by": [
+        "generate-tech-docs",
+        "review-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "validate-traces"
+      ],
+      "why": "Nguồn của tech_doc_revision + TECHDOC_DRIFT."
+    },
+    {
+      "name": "@trace.api_source",
+      "artifact": ".feature + tech-design.md",
+      "scope": "file",
+      "written_by": [
+        "generate-bdd",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "review-tech-docs",
+        "review-context"
+      ],
+      "why": "existing → bỏ cổng T7 + skip System BDD Synthesis S1-S3."
+    },
+    {
+      "name": "@trace.stub",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "why": "Method trắng nội-feature. Nguồn của STUB_UNRESOLVED."
+    },
+    {
+      "name": "@trace.mock_for",
+      "artifact": "code",
+      "scope": "class",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "generate-code"
+      ],
+      "why": "Đánh dấu layer mock của FE `--phase=ui` thuộc UC nào. `--phase=integration` dò lại chính tag này để biết mock nào phải thay bằng adapter thật — vừa ghi vừa đọc bởi cùng lệnh ở HAI phase khác nhau, đó là đúng."
+    },
+    {
+      "name": "@trace.mock_source",
+      "artifact": "code",
+      "scope": "class",
+      "values": "contract | system-bdd",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "generate-code"
+      ],
+      "why": "Shape của mock suy từ đâu. `system-bdd` = infer từ behavior (KHÔNG phải full request/response shape) → phase integration phải dự kiến điều chỉnh; `contract` = lấy từ §4 tech-doc, khớp sẵn."
+    },
+    {
+      "name": "@trace.system_bdd",
+      "artifact": "code",
+      "scope": "class",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [],
+      "allow_no_reader": "Con trỏ tới System BDD mà mock được dựng theo. Nhãn truy vết cho người đọc + reviewer; không có consumer tự động (phase integration route bằng @trace.mock_for/@trace.mock_source).",
+      "why": "Ghi mock này dựng theo file System BDD nào."
+    },
+    {
+      "name": "@trace.be_contract",
+      "artifact": "code",
+      "scope": "class",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [],
+      "allow_no_reader": "CHỈ có khi mock_source=contract — ghi tech-doc nào cấp shape. Nhãn truy vết, không có consumer tự động.",
+      "why": "Con trỏ tới tech-doc cấp shape cho mock."
+    },
+    {
+      "name": "@trace.root_cause",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "fix-bug"
+      ],
+      "read_by": [],
+      "allow_no_reader": "Nhãn cho người đọc code — mô tả ngắn nguyên nhân gốc của bug đã fix. Cùng nhóm với @trace.fixes.",
+      "why": "Ghi lại nguyên nhân gốc tại chỗ sửa."
+    },
+    {
+      "name": "@trace.regression",
+      "artifact": "test",
+      "scope": "method",
+      "written_by": [
+        "fix-bug"
+      ],
+      "read_by": [],
+      "allow_no_reader": "Đánh dấu test hồi quy sinh kèm bản fix. Nhãn cho người đọc; test_count/test_classes trong TSV mới là đường máy đọc (G7).",
+      "why": "Nhận diện test hồi quy của một ticket."
+    },
+    {
+      "name": "@trace.title",
+      "artifact": ".feature",
+      "scope": "file",
+      "written_by": [
+        "feature-template"
+      ],
+      "read_by": [
+        "review-context"
+      ],
+      "why": "Tên feature dạng người đọc. review-context B5 Nhóm B chỉ kiểm CÓ MẶT, không kiểm giá trị."
+    },
+    {
+      "name": "@trace.author",
+      "artifact": ".feature",
+      "scope": "file",
+      "written_by": [
+        "feature-template"
+      ],
+      "read_by": [
+        "review-context"
+      ],
+      "why": "Nguồn gốc file (`AI-generated`). Chỉ kiểm có mặt — xem @trace.title."
+    },
+    {
+      "name": "@trace.created_at",
+      "artifact": ".feature",
+      "scope": "file",
+      "written_by": [
+        "feature-template"
+      ],
+      "read_by": [
+        "review-context"
+      ],
+      "why": "Ngày tạo file. Chỉ kiểm có mặt — xem @trace.title. KHÁC last_updated của TSV (cái đó là trạng thái, cái này là gốc)."
+    },
+    {
+      "name": "@trace.generated_at",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "written_by": [
+        "tech-design-template"
+      ],
+      "read_by": [],
+      "allow_no_reader": "Ngày sinh tech-doc. Drift của tech-doc đo bằng @trace.revision (integer), KHÔNG bằng ngày — nên field này thuần thông tin cho người đọc.",
+      "why": "Ngày sinh tech-doc, dạng người đọc."
+    },
+    {
+      "name": "@trace.business_rules",
+      "artifact": ".feature",
+      "scope": "scenario",
+      "shape": "{TICKET-ID}-UC{N}-BR{m}, …",
+      "written_by": [
+        "generate-bdd",
+        "feature-template",
+        "propose-scenario"
+      ],
+      "read_by": [
+        "review-context"
+      ],
+      "$reader_note": "generate-tech-docs đọc BR ID từ THÂN scenario (`BR{m}`), không đọc tag này — nên nó không phải consumer.",
+      "why": "Link scenario ↔ Business Rule của PRD. BR đánh số LIÊN TỤC toàn PRD (không reset theo UC — G14), nên ID ở đây phải lấy NGUYÊN từ PRD §3. Mở cột bảng BR trên PRD đã có BDD sẽ làm churn ID và phá link này."
+    },
+    {
+      "name": "@trace.dataset",
+      "artifact": ".feature",
+      "scope": "file",
+      "$producer_note": "CHỈ feature-template — nó được {{include}} nướng cứng vào generate-bdd lúc build, nên generate-bdd không nhắc tên field này ở prose của chính nó. Khai thêm generate-bdd sẽ làm R3 fail.",
+      "written_by": [
+        "feature-template"
+      ],
+      "read_by": [
+        "review-context",
+        "validate-traces"
+      ],
+      "why": "File testdata dùng chung của feature. Đổi nó là thay đổi CẤP FILE mà sc_version không thấy — chính vì vậy Step 5c liệt nó vào nguồn của BDD_DRIFT."
+    },
+    {
+      "name": "@trace.prd",
+      "artifact": ".feature",
+      "scope": "file",
+      "shape": "{TICKET-ID}",
+      "$producer_note": "CHỈ feature-template — xem @trace.dataset.",
+      "written_by": [
+        "feature-template"
+      ],
+      "read_by": [
+        "review-context"
+      ],
+      "why": "Con trỏ ngược .feature → PRD. Mang TICKET-ID chứ không phải path, vì tech-doc và trace cũng khoá theo TICKET-ID."
+    },
+    {
+      "name": "@trace.platforms",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "shape": "danh sách platform",
+      "written_by": [
+        "generate-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "review-tech-docs"
+      ],
+      "why": "Số NHIỀU, cố ý khác @trace.platform (scalar, ở .feature) — cùng lý do như bdd_version vs bdd_versions (G15): tech-doc là doc GỘP phủ nhiều platform."
+    },
+    {
+      "name": "@trace.test_type",
+      "artifact": "test",
+      "scope": "method",
+      "written_by": [
+        "dev-gen-test"
+      ],
+      "read_by": [],
+      "allow_no_reader": "NHÃN CHẾT — phát hiện khi khai schema (G30 lô 3). /dev-gen-test dán nó lên mọi test class nhưng KHÔNG lệnh nào đọc: dev-run-test chạy theo test_command của project, qc-* dùng stack riêng. Giữ vì nó là nhãn hữu ích cho người đọc code và là chỗ móc sẵn nếu sau này muốn chạy test theo loại (vd chỉ chạy unit ở pre-commit). Nếu 6 tháng nữa vẫn không consumer nào → bỏ hẳn thay vì để nợ.",
+      "why": "Phân loại test (unit/integration/e2e…). Hiện chỉ là nhãn cho người đọc."
+    },
+    {
+      "name": "@trace.testid_attr",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "written_by": [
+        "map-testids"
+      ],
+      "read_by": [
+        "generate-code",
+        "qc-run-test",
+        "qc-design-test"
+      ],
+      "$history_note": "G30 lô 3 phát hiện field này TỰ MÔ TẢ là contract FE↔QC nhưng chỉ nửa FE (generate-code) đọc — QC tự suy tên thuộc tính từ platform. G37 nối nửa QC: qc-run-test đọc để CẤU HÌNH test-id attribute (Playwright get_by_test_id mặc định dò `data-testid`; dự án dùng `data-test`/`data-qa` sẽ trượt 100% locator nếu không set), qc-design-test ghi lại vào metadata .Test.md để reviewer đối chiếu.",
+      "why": "Tên thuộc tính test-id của stack — contract FE↔QC. FE emit theo nó (generate-code), QC cấu hình locator theo nó (qc-run-test). Suy từ platform thay vì đọc field = phát biểu lại sự thật đã ghi ở nơi khác, và hỏng IM LẶNG: test fail 'element not found' trông y hệt bug sản phẩm."
+    },
+    {
+      "name": "@trace.domain",
+      "artifact": ".feature + tech-design.md",
+      "scope": "file",
+      "written_by": [
+        "generate-bdd",
+        "feature-template",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "context-loader",
+        "review-context",
+        "review-tech-docs",
+        "generate-spec-manifest",
+        "setup-ai-first"
+      ],
+      "why": "Khoá ĐỊNH TUYẾN. context-loader Bước 1.5 đọc nó từ frontmatter target để chọn service submodule — sai là ghi code/trace nhầm repo mà không báo gì."
+    },
+    {
+      "name": "@trace.id",
+      "artifact": ".feature + tech-design.md",
+      "scope": "file",
+      "shape": "{TICKET-ID}-UC{N}",
+      "written_by": [
+        "feature-template",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "generate-code",
+        "generate-tech-docs",
+        "qc-analyze",
+        "review-context"
+      ],
+      "why": "UC-ID của file. generate-code đọc nó để chốt Scope Lock (implement ĐÚNG UC này, không lan sang .feature khác)."
+    },
+    {
+      "name": "@trace.module",
+      "artifact": ".feature + tech-design.md",
+      "scope": "file",
+      "written_by": [
+        "feature-template",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "dev-gen-test",
+        "generate-tech-docs",
+        "review-context"
+      ],
+      "why": "Stack module của service sở hữu. dev-gen-test dùng để chọn test pattern. Giá trị `unknown` ở spec repo mode là HỢP LỆ — review-context không được flag."
+    },
+    {
+      "name": "@trace.ucs",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "shape": "danh sách UC-ID",
+      "written_by": [
+        "generate-tech-docs",
+        "tech-design-template"
+      ],
+      "read_by": [
+        "review-tech-docs",
+        "gate"
+      ],
+      "why": "Tech-doc là doc GỘP cấp PRD — đây là danh sách UC nó phủ. Cần vì tên file mang {TICKET-ID} chứ không mang {UC-ID} (G10): gate phải tách TICKET-ID rồi glob, và dùng field này để biết doc có phủ UC đang hỏi không."
+    },
+    {
+      "name": "@trace.seam_port",
+      "artifact": "code",
+      "scope": "class",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "review-code"
+      ],
+      "why": "Tên port mà class stub đang giả lập. Đi CẶP với @trace.seam_pending — review-code kiểm cả hai phải có mặt cùng dòng `PENDING` trong _seams.tsv. validate-traces Step 5b nhận diện seam qua @trace.seam_pending + cột `name` của sổ, KHÔNG đọc tag này."
+    },
+    {
+      "name": "@trace.stub_owner",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "why": "UC lẽ ra phải lấp method trắng này. Step 5b hỏi 'owner đã gen chưa' để quyết STUB_PENDING (ⓘ) vs STUB_UNRESOLVED (🔴 chặn PR). Mất tag = mất luôn phép phân biệt đó → hoặc báo động oan mọi stub, hoặc bỏ sót hàm trắng mồ côi."
+    },
+    {
+      "name": "@trace.stub_for",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "why": "Trách nhiệm mà method trắng này đang giữ chỗ. Step 5b dùng nó để dò 'có hàm THẬT song song cùng trách nhiệm không' — dấu hiệu Fill-before-create đã trượt (BDD owner đẻ hàm mới thay vì lấp hàm cũ)."
+    },
+    {
+      "name": "@trace.sign_off",
+      "artifact": "tech-design.md",
+      "scope": "file",
+      "written_by": [
+        "review-tech-docs"
+      ],
+      "read_by": [
+        "review-tech-docs"
+      ],
+      "why": "Cổng T7 — xác nhận cross-team của tech-doc system BDD. Vừa ghi vừa đọc bởi cùng một lệnh là ĐÚNG (nó là sổ trạng thái nội bộ của cổng đó, không phải contract liên lệnh). LƯU Ý: tech-design.template.md KHÔNG phát ra field này — review-tech-docs tự thêm khi thiếu, nên template không phải producer."
+    },
+    {
+      "name": "@trace.seam_pending",
+      "artifact": "code",
+      "scope": "class",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "why": "Port cross-UC chưa có hàng thật. Nguồn của SEAM_UNWIRED."
+    },
+    {
+      "name": "@trace.service",
+      "artifact": ".feature",
+      "scope": "file",
+      "written_by": [
+        "generate-bdd",
+        "feature-template"
+      ],
+      "read_by": [
+        "generate-bdd",
+        "dev-gen-test",
+        "generate-tech-docs",
+        "review-context"
+      ],
+      "why": "Nguồn DUY NHẤT của cột TSV `service` (cột 23) — trace gộp không tách theo service nên thiếu tag này là mất hẳn thông tin sở hữu ở cấp row. BẮT BUỘC mọi mode từ v0.4.3 (trước đó feature.template chủ động bỏ ở spec repo mode, và review-context xếp nó vào Nhóm C có-điều-kiện)."
+    },
+    {
+      "name": "@trace.design_spec_version",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "why": "Nguồn của DESIGNSPEC_DRIFT (Step 5d). CHỈ FE/App — bỏ hẳn dòng tag với system/backend."
+    },
+    {
+      "name": "@trace.fixes",
+      "artifact": "code",
+      "scope": "method",
+      "written_by": [
+        "fix-bug"
+      ],
+      "read_by": [],
+      "allow_no_reader": "Nhãn cho người đọc code, không có consumer tự động."
+    }
+  ],
+  "tsv_columns": [
+    {
+      "n": 1,
+      "name": "sc_id",
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "dev-gen-test",
+        "dev-run-test",
+        "qc-run-test",
+        "report-bug",
+        "fix-bug"
+      ]
+    },
+    {
+      "n": 2,
+      "name": "sc_title",
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 3,
+      "name": "spec_ver",
+      "written_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 4,
+      "name": "gen_ver",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 5,
+      "name": "implemented_by",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 6,
+      "name": "test_count",
+      "written_by": [
+        "dev-gen-test",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 7,
+      "name": "test_classes",
+      "written_by": [
+        "dev-gen-test",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 8,
+      "name": "dev_selftest",
+      "$invalidated_by_comment": [
+        "PRODUCER vs INVALIDATOR — hai vai khác nhau, cùng nằm trong written_by.",
+        "Chủ sở hữu (ghi giá trị KHẲNG ĐỊNH pass/fail): dev-run-test.",
+        "Invalidator (chỉ được hạ về not_run/— khi giá trị cũ HẾT ĐÚNG): generate-bdd (spec đổi),",
+        "generate-code (lấp stub hoặc sửa method do DRIFT), fix-bug (code đổi), dev-gen-test (test mới).",
+        "Luật đầy đủ: rules/workflow.md §Trace Contract — 'Làm mất hiệu lực ≠ ghi đè'.",
+        "Vì sao cần: giữ một 'pass' sinh ra từ spec đã bị sửa là BÁO CÁO SAI. Trước G28 chỉ",
+        "nhánh lấp-stub hạ cờ, nên chuỗi spec-đổi → DRIFT → regen → OK kết thúc bằng dashboard",
+        "xanh hoàn toàn trên một hành vi chưa từng được test."
+      ],
+      "written_by": [
+        "dev-run-test",
+        "dev-gen-test",
+        "generate-code",
+        "generate-bdd",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 9,
+      "name": "dev_selftest_at",
+      "$comment": "Chủ: dev-run-test. Invalidator (hạ về —): generate-bdd · generate-code · fix-bug. Xem dev_selftest.",
+      "written_by": [
+        "dev-run-test",
+        "generate-code",
+        "generate-bdd",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 10,
+      "name": "qc_status",
+      "$comment": "Chủ (ghi pass/fail/skip): qc-run-test — DUY NHẤT. Invalidator (chỉ hạ về not_run khi spec/code vừa đổi): generate-bdd · generate-code. Xem dev_selftest + rules/workflow.md 'Làm mất hiệu lực ≠ ghi đè'.",
+      "written_by": [
+        "qc-run-test",
+        "generate-bdd",
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "dev-run-test",
+        "generate-code",
+        "report-bug",
+        "fix-bug"
+      ]
+    },
+    {
+      "n": 11,
+      "name": "qc_run_at",
+      "$comment": "Chủ: qc-run-test. Invalidator (hạ về —): generate-bdd · generate-code. Xem qc_status.",
+      "written_by": [
+        "qc-run-test",
+        "generate-bdd",
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "dev-run-test",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 12,
+      "name": "qc_owner",
+      "written_by": [
+        "qc-run-test",
+        "report-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "fix-bug"
+      ]
+    },
+    {
+      "n": 13,
+      "name": "qc_blocked_by",
+      "written_by": [
+        "qc-run-test",
+        "report-bug"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 14,
+      "name": "prd_version",
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 15,
+      "name": "bdd_version",
+      "written_by": [
+        "generate-bdd",
+        "review-context"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 16,
+      "name": "tech_doc_revision",
+      "written_by": [
+        "generate-code",
+        "review-tech-docs"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 17,
+      "name": "fe_tech_doc_revision",
+      "written_by": [
+        "generate-code"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd",
+        "review-tech-docs"
+      ]
+    },
+    {
+      "n": 18,
+      "name": "prd_status",
+      "written_by": [
+        "generate-bdd",
+        "validate-traces"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 19,
+      "name": "uc_status",
+      "written_by": [
+        "generate-bdd",
+        "validate-traces",
+        "review-context"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code"
+      ]
+    },
+    {
+      "n": 20,
+      "name": "fe_phase",
+      "written_by": [
+        "generate-code",
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 21,
+      "name": "status",
+      "written_by": [
+        "validate-traces",
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code",
+        "dev-run-test",
+        "qc-run-test"
+      ]
+    },
+    {
+      "n": 23,
+      "name": "service",
+      "$comment": [
+        "Đội/submodule sở hữu scenario. Nguồn: @trace.service của header .feature.",
+        "VÌ SAO TỒN TẠI (G31): validate-traces Step 0 và trace-mirror.md đều khẳng định trace gộp",
+        "'không cần tách theo service vì mỗi row mang @trace.service' — nhưng TSV KHÔNG có cột nào",
+        "cho nó và JSON report cũng không. Ở đúng chế độ phổ biến nhất (umbrella + spec_source),",
+        "trace hoàn toàn không trả lời được 'scenario này thuộc đội nào' — câu hỏi số MỘT của một",
+        "dự án nhiều đội. Nghịch lý: nhánh LEGACY (trace tách theo service) thì CÓ gắn field service",
+        "vào JSON; nhánh 'phổ biến' thì không. Cột này làm lời khẳng định kia thành sự thật.",
+        "Giá trị: path service | 'multi' (chưa chốt) | 'unresolved' (routing sai) | '—' (single-service)."
+      ],
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 24,
+      "name": "design_spec_version",
+      "$comment": [
+        "Version design-spec tại thời điểm sinh BDD. Nguồn: | **Version** | của design-spec.",
+        "VÌ SAO TỒN TẠI (G32): design-spec điều khiển CẢ BDD FE/App (Screen States + AC-UI) LẪN code",
+        "FE (màn hình, component inventory, Figma frame) — nhưng là artifact upstream DUY NHẤT không",
+        "có cột TSV, không có tag trong code, không có cờ drift. Nó tự bảo vệ một chiều (reset draft",
+        "khi PRD đổi), còn chiều 'designer sửa design-spec SAU KHI BDD/code đã sinh' thì không gì bắt.",
+        "GAPS.md G2 mở đầu bằng 'tầng BDD là tầng DUY NHẤT không có cờ drift' — câu đó đúng lúc viết,",
+        "vì bảng kiểm kê chỉ tính PRD/BDD/tech-doc/code. Design-spec không nằm trong bảng nên không ai đếm.",
+        "'—' cho system/backend và khi sinh BDD mà không có design-spec."
+      ],
+      "written_by": [
+        "generate-bdd"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    },
+    {
+      "n": 22,
+      "name": "last_updated",
+      "written_by": [
+        "generate-bdd",
+        "generate-code",
+        "dev-gen-test",
+        "dev-run-test",
+        "qc-run-test",
+        "review-context",
+        "review-tech-docs",
+        "fix-bug"
+      ],
+      "read_by": [
+        "validate-traces"
+      ]
+    }
+  ],
+  "aux_tables": [
+    {
+      "$comment": [
+        "Bảng phụ ngoài TSV chính. Nằm ngoài SoT cho tới G30 — dù nó là NGUỒN của hai cờ 🔴",
+        "chặn PR (SEAM_UNWIRED, STUB_UNRESOLVED). Đổi tên/thứ tự cột mà không ai bắt được."
+      ],
+      "name": "_seams.tsv",
+      "path": "{trace_dir}/{domain}/{prd-slug}/_seams.tsv",
+      "columns": [
+        "kind",
+        "name",
+        "consumer_uc",
+        "owner_uc",
+        "artifact",
+        "binding",
+        "status",
+        "last_updated"
+      ],
+      "written_by": [
+        "generate-code",
+        "validate-traces"
+      ],
+      "read_by": [
+        "validate-traces",
+        "review-code"
+      ],
+      "column_actors": [
+        "generate-code",
+        "validate-traces"
+      ],
+      "$column_actors_note": "Chỉ hai lệnh này thao tác ở MỨC CỘT (ghi/parse từng field). review-code là consumer ở MỨC BẢNG — nó chỉ kiểm 'có dòng PENDING tương ứng trong sổ không', không đọc tên cột. Tách ra để R3 đừng đòi review-code nhắc đủ 8 tên cột."
+    }
+  ],
+  "queues": [
+    {
+      "$comment": [
+        "Hàng đợi feedback từ tester/QC. Khai ở đây để R1 bắt được ca 'hàng đợi mất consumer'",
+        "y như nó bắt field mất producer — đó chính là hình dạng của G26."
+      ],
+      "name": "bug-reports",
+      "path_key": "bug_reports_dir",
+      "written_by": [
+        "report-bug"
+      ],
+      "read_by": [
+        "fix-bug",
+        "qc-run-test"
+      ]
+    },
+    {
+      "name": "bdd-proposals",
+      "path_key": "bdd_proposals_dir",
+      "written_by": [
+        "propose-scenario"
+      ],
+      "read_by": [
+        "generate-bdd"
+      ]
+    },
+    {
+      "name": "prd-change-requests",
+      "path_key": "prd_change_requests_dir",
+      "written_by": [
+        "propose-scenario",
+        "extend-prd"
+      ],
+      "read_by": [
+        "extend-prd",
+        "validate-traces"
+      ],
+      "$roles_note": "extend-prd là consumer DRAIN thật (Bước 2 đọc request accepted làm nguyên liệu; Bước 6.5 đóng dấu incorporated + chuyển sang archived/ + commit) — nên nó vừa read vừa write. validate-traces Step 7b chỉ ĐẾM và nhắc (không drain). G26 đóng đủ 3 phần từ đây."
+    }
+  ],
+  "vocabularies": {
+    "$comment": "Mọi giá trị phải xuất hiện ở ít nhất một actor — giá trị chết là dấu hiệu contract lệch.",
+    "trace_status": {
+      "values": [
+        "OK",
+        "DRIFT",
+        "GAP",
+        "UNTRACKED",
+        "ORPHANED"
+      ],
+      "column": "status"
+    },
+    "platform": {
+      "values": [
+        "web",
+        "app",
+        "system"
+      ]
+    },
+    "approval_status": {
+      "values": [
+        "draft",
+        "in-review",
+        "approved"
+      ]
+    },
+    "fe_phase": {
+      "values": [
+        "ui",
+        "integrated"
+      ],
+      "column": "fe_phase"
+    },
+    "seam_status": {
+      "values": [
+        "PENDING",
+        "READY",
+        "RESOLVED"
+      ]
+    },
+    "audit_flags": {
+      "values": [
+        "PRD_DRIFT",
+        "PRD_STALE_REF",
+        "BDD_DRIFT",
+        "TECHDOC_DRIFT",
+        "TECHDOC_STALE_REF",
+        "FE_TECHDOC_DRIFT",
+        "TECHDOC_STALE_VS_BDD",
+        "DESIGNSPEC_DRIFT",
+        "DESIGNSPEC_STALE_VS_BDD",
+        "TRACE_ORPHAN",
+        "SEAM_UNWIRED",
+        "STUB_UNRESOLVED",
+        "SEAM_PENDING",
+        "STUB_PENDING"
+      ]
+    }
+  },
+  "path_keys": {
+    "$comment": "Key phải có trong templates/project-context.yaml VÀ được dùng bởi ít nhất một actor. Key khai mà không ai dùng = key chết (GAPS.md G17).",
+    "config_file": "templates/project-context.yaml",
+    "ignore_unused": [
+      "specs_dir",
+      "src_dir",
+      "trace_dir",
+      "tech_docs_dir",
+      "lessons_file"
+    ]
+  },
+  "forbidden_patterns": [
+    {
+      "pattern": "bdd/{UC-ID}.feature",
+      "reason": "@trace.source thiếu segment {platform}. Layout thật: bdd/{platform}/{UC-ID}-{slug}.feature",
+      "gap": "G8"
+    },
+    {
+      "pattern": "{UC-ID}*-tech-design",
+      "reason": "Glob không bao giờ khớp: tech-doc là doc GỘP cấp PRD, tên mang {TICKET-ID} chứ không mang {UC-ID}",
+      "gap": "G10",
+      "except": {
+        "steps/gate.md": "Trích dẫn pattern trong cảnh báo tại chỗ: \"Đừng glob {UC-ID}*-tech-design*.md — nó nở thành ... và không bao giờ khớp\""
+      }
+    },
+    {
+      "pattern": "{prd-slug}/{UC-ID}.tsv",
+      "reason": "Tên sổ trace thiếu -{platform}. Một sổ cho mỗi UC × platform",
+      "gap": "G18"
+    },
+    {
+      "pattern": "@trace.uc=",
+      "reason": "Từ vựng ĐÃ KHAI TỬ (G11). Số UC đã nằm trong `sc_id` (`{UC-ID}-SC{N}`) nên tag riêng là thừa và gây nhập nhằng với `@trace.ucs` (danh sách UC của tech-doc). Ba file dưới được phép chứa vì chúng đang MAP NGƯỢC nó sang canonical rồi strip — không phải phát ra nó.",
+      "gap": "G11/G30",
+      "except": {
+        "commands/generate-bdd.tmpl": "Đường backward-compat khi nhặt proposal cũ từ feedback/bdd-proposals/",
+        "commands/propose-scenario.tmpl": "Ghi chú cho tester đừng dùng lại format cũ",
+        "commands/review-context.tmpl": "B5 auto-fix: map tag lạc sang canonical rồi strip"
+      }
+    },
+    {
+      "pattern": "@trace.ac=",
+      "reason": "Từ vựng ĐÃ KHAI TỬ (G11) — thay bằng dòng `# Covers: AC{N}`. Xem @trace.uc=.",
+      "gap": "G11/G30",
+      "except": {
+        "commands/generate-bdd.tmpl": "Đường backward-compat cho proposal cũ",
+        "commands/propose-scenario.tmpl": "Ghi chú format cũ",
+        "commands/review-context.tmpl": "B5 auto-fix map sang `# Covers:`"
+      }
+    },
+    {
+      "pattern": "claude-opus-4",
+      "reason": "Hardcode version model — dùng \"model Opus mới nhất\" để không phải sửa framework mỗi lần lên model",
+      "gap": "G21"
+    },
+    {
+      "pattern": "{paths.feature_template}",
+      "reason": "Key chết: template được {{include}} nướng cứng lúc build, lệnh không đọc path template lúc chạy",
+      "gap": "G17"
+    },
+    {
+      "pattern": "{paths.prd_template}",
+      "reason": "Key chết — xem G9/G17",
+      "gap": "G17"
+    },
+    {
+      "pattern": "{paths.trace_report}",
+      "reason": "Key chết và trỏ sai: report thật là {trace_dir}/trace-report.json",
+      "gap": "G17"
+    },
+    {
+      "pattern": "{paths.templates_dir}",
+      "reason": "Key chết — xem G17",
+      "gap": "G17"
+    }
+  ]
+}