@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/bin/trace-schema.json

@@ -1,692 +1,1449 @@
-{
-  "$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",
-    "sync": "commands/sync.tmpl",
-    "setup-ai-first": "commands/setup-ai-first.tmpl",
-    "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.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.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",
-      "written_by": [
-        "dev-run-test",
-        "dev-gen-test",
-        "generate-code",
-        "fix-bug"
-      ],
-      "read_by": [
-        "validate-traces",
-        "qc-run-test"
-      ]
-    },
-    {
-      "n": 9,
-      "name": "dev_selftest_at",
-      "written_by": [
-        "dev-run-test",
-        "generate-code",
-        "fix-bug"
-      ],
-      "read_by": [
-        "validate-traces",
-        "qc-run-test"
-      ]
-    },
-    {
-      "n": 10,
-      "name": "qc_status",
-      "written_by": [
-        "qc-run-test"
-      ],
-      "read_by": [
-        "validate-traces",
-        "dev-run-test",
-        "generate-code",
-        "report-bug",
-        "fix-bug"
-      ]
-    },
-    {
-      "n": 11,
-      "name": "qc_run_at",
-      "written_by": [
-        "qc-run-test"
-      ],
-      "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": 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"
-      ]
-    }
-  ],
-  "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",
-        "BDD_DRIFT",
-        "TECHDOC_DRIFT",
-        "FE_TECHDOC_DRIFT",
-        "TECHDOC_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": "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"
-    }
-  ]
-}
+{
+  "$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.",
+    "$lint_binding_comment": [
+      "BINDING CHO lint-trace (G38). R6 canh 'giá trị có được actor nào DÙNG không' — đó là",
+      "câu hỏi về contract. Nhưng nó không trả lời được 'file .tsv THẬT có tuân enum này không',",
+      "vì không rule nào mở sổ thật ra xem. bin/lint-trace.js làm việc đó, và nó cần biết mỗi",
+      "vocabulary neo vào ĐÂU. Mỗi vocabulary PHẢI khai đúng một trong:",
+      "  column           → một cột của TSV chính",
+      "  columns          → nhiều cột của TSV chính",
+      "  aux_table + aux_column → một cột của bảng phụ trong aux_tables",
+      "  filename_segment → một đoạn trong tên file sổ",
+      "  $lint            → cố ý ngoài phạm vi lint, PHẢI nêu lý do",
+      "Thiếu tất cả → self-check.js R8a fail build. Đây là van chống lặp lại chính G38:",
+      "thêm vocabulary mới mà quên dạy checker thì build đỏ, không phải 6 tháng sau mới biết."
+    ],
+    "trace_status": {
+      "values": [
+        "OK",
+        "DRIFT",
+        "GAP",
+        "UNTRACKED",
+        "ORPHANED"
+      ],
+      "column": "status"
+    },
+    "platform": {
+      "values": [
+        "web",
+        "app",
+        "system"
+      ],
+      "filename_segment": "{UC-ID}-{platform}.tsv",
+      "$filename_note": "Tên sổ là nơi DUY NHẤT mang platform của row — validate-traces Step 2 lấy platform từ đây để tìm .feature đúng thư mục con. Sổ thiếu đoạn này thì cả sổ vô hình (đúng hình dạng G3/G8)."
+    },
+    "approval_status": {
+      "values": [
+        "draft",
+        "in-review",
+        "approved"
+      ],
+      "columns": [
+        "prd_status",
+        "uc_status"
+      ]
+    },
+    "fe_phase": {
+      "values": [
+        "ui",
+        "integrated"
+      ],
+      "column": "fe_phase"
+    },
+    "dev_selftest_status": {
+      "$comment": [
+        "G49 — hai cột này mang enum nhưng trước đó KHÔNG có vocabulary, nên lint T3 không canh:",
+        "`dev_selftest = passed`, `qc_status = OK`, `qc_status = pending` đều đi qua sạch.",
+        "Mà đây là hai cột của G28 ('cờ nói dối') và là hai cột có NHIỀU NGƯỜI GHI NHẤT trong",
+        "schema — 5 lệnh và 3 lệnh, mỗi lệnh ở một nhánh điều kiện khác nhau, tất cả bằng prose.",
+        "Cột dễ lệch giá trị nhất trong sổ, và là cột duy nhất mang enum mà không được canh.",
+        "",
+        "VÌ SAO SỐNG ĐƯỢC QUA G30: G30 mở phạm vi schema cho TAG (@trace.*). Hai cột này không",
+        "có tag tương ứng — chúng chỉ sống trong TSV. Nên chúng nằm ngoài lăng kính của G30, và",
+        "trước G38 thì không có lăng kính nào soi cột-không-có-tag."
+      ],
+      "values": [
+        "pass",
+        "fail",
+        "not_run"
+      ],
+      "column": "dev_selftest"
+    },
+    "qc_run_status": {
+      "$comment": "Xem dev_selftest_status. Có thêm `skip` — QC chủ động bỏ qua scenario (khác not_run: chưa chạy).",
+      "values": [
+        "pass",
+        "fail",
+        "skip",
+        "not_run"
+      ],
+      "column": "qc_status"
+    },
+    "seam_status": {
+      "values": [
+        "PENDING",
+        "READY",
+        "RESOLVED"
+      ],
+      "aux_table": "_seams.tsv",
+      "aux_column": "status"
+    },
+    "audit_flags": {
+      "$lint": "n/a — không sống trong TSV. Cờ audit được tính lúc chạy và sống trong trace-report.json (issues + summary counter); R7 canh đủ ba tầng của chúng. lint-trace chỉ kiểm file trên đĩa, nên không có gì để neo.",
+      "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"
+      ]
+    }
+  },
+  "gate": {
+    "$comment": [
+      "CỔNG CHẶN PR (G39). README khai bằng chữ in đậm rằng 4 cờ này 'chặn PR', kèm câu",
+      "'build xanh + test từng-UC xanh KHÔNG phát hiện được' — đó là điểm bán hàng cốt lõi.",
+      "Nhưng trước G39 không có gì chặn: 0 CI, 0 git hook, 0 exit code. /validate-traces in",
+      "một report vào terminal Claude Code, nơi không CI nào đọc được. Kỷ luật là honor-system,",
+      "và cái gì không chặn thì sau sprint thứ ba không ai làm.",
+      "",
+      "bin/gate-trace.js đọc khối này để biết ĐẾM CỜ NÀO — không hard-code. Vì sao quan trọng:",
+      "gate đọc summary[counter]. Nếu counter bị đổi tên mà gate không biết, `undefined > 0`",
+      "là false ⇒ GATE PASS TRÊN CODE HỎNG. Đó là false-green im lặng, đúng hình dạng G1.",
+      "Nên gate PHẢI fail khi counter nó chờ không có mặt trong report, và self-check R9 canh",
+      "cả hai đầu (counter có trong summary của validate-traces · issues_key có trong issues).",
+      "",
+      "Cờ 🟠 (PRD_DRIFT, BDD_DRIFT, TECHDOC_DRIFT, …) CỐ Ý không nằm đây — chúng là 'code chưa",
+      "theo kịp spec', một loại nợ khác, không làm hỏng luồng đang chạy. Chặn PR vì nợ là làm",
+      "cổng bị tắt. Xem README §Traceability."
+    ],
+    "report_path": "{trace_dir}/trace-report.json",
+    "config_preconditions": {
+      "$comment": [
+        "TẦNG G0 — 'sổ có ĐƯỢC BẢO VỆ không?', hỏi TRƯỚC cả ba tầng kia.",
+        "",
+        "Vì sao tách khỏi `blocking`: `blocking` có nghĩa hẹp là CODE ĐANG HỎNG (4 cờ 🔴), và",
+        "R9(e) tồn tại để giữ đúng ranh giới đó — nó fail build nếu ai nhét một cờ NỢ (🟠) vào.",
+        "Hai điều kiện dưới đây thuộc loại THỨ BA: chưa có gì sai, nhưng LƯỚI AN TOÀN ĐANG TẮT.",
+        "Ví như: động cơ hỏng (🔴) · đến hạn thay dầu (🟠) · CHƯA CÀI DÂY AN TOÀN (G0).",
+        "Trộn chúng vào `blocking` là làm mờ chính ranh giới R9(e) bảo vệ.",
+        "",
+        "Vì sao hỏi TRƯỚC: G1 kiểm rất kỹ cấu trúc của một quyển sổ mà có thể KHÔNG NẰM TRONG",
+        "GIT. Kiểm cấu trúc của thứ sắp mất thì vô nghĩa.",
+        "",
+        "Cách hoạt động: cả hai điều kiện đã được `bin/lint-trace.js` phát hiện dưới dạng WARN.",
+        "gate NÂNG chúng thành lỗi chặn. Một implementation, hai mức nghiêm trọng — cố ý:",
+        "  pre-push (lint) → NHẮC. Chặn push vì một dòng cấu hình sẽ dạy dev gõ --no-verify,",
+        "                    và mất luôn phần lint THẬT (sổ hỏng cấu trúc).",
+        "  CI (gate)       → CHẶN. Đây là chỗ đúng để chặn.",
+        "Cùng cách phân vai G39 đã chọn cho pre-push vs CI."
+      ],
+      "promote_lint_rules": [
+        {
+          "rule": "T11",
+          "why": "sổ trace đang bị gitignore — nó KHÔNG được lưu vào git, mất là mất toàn bộ (G29)"
+        },
+        {
+          "rule": "T10",
+          "why": "sổ thiếu luật merge — hai nhánh cùng ghi sẽ mất row của nhau, im lặng (G40)"
+        }
+      ]
+    },
+    "checkpoint_levels": {
+      "$comment": [
+        "MỨC CHẶN CHECKPOINT CỦA TỪNG LỆNH (nợ 'nhãn chặn cứng' sau G41).",
+        "",
+        "G41 viết ba mức vào steps/gate.md Bước 3a — nhưng KHÔNG lệnh nào tự khai mình thuộc",
+        "mức nào. Nên agent phải TỰ SUY từ bảng đó mỗi lần đọc: '/extend-prd sửa một PRD đã",
+        "duyệt — có tính là ghi đè file đã có không?'. Suy đúng thì không sao; suy sai một lần",
+        "theo hướng nhẹ hơn thì `--yes` bỏ qua được một cổng đáng ra KHÔNG BAO GIỜ được bỏ.",
+        "",
+        "Đây là hình dạng đã gặp bốn lần trong loạt GAP này: luật ĐÚNG, viết RÕ, và KHÔNG AI",
+        "CANH. G1 ('phải bump sc_version') · G28 ('đổi spec thì hạ qc_status') · G41 ('read-only",
+        "được miễn CHECKPOINT' — gate không thi hành) · và cái này. Ba lần trước đều chữa bằng",
+        "cùng một cách: khai tường minh + để máy canh. R11 là phần 'máy canh'.",
+        "",
+        "KHÔNG liệt kê `normal`: nó là mặc định, và liệt kê ra là tạo một danh sách phải bảo",
+        "trì mãi mãi — thêm lệnh mới mà quên thêm vào đó thì lại sai lần nữa.",
+        "",
+        "PHẠM VI: `hard` là 'ghi đè thứ NGƯỜI DÙNG ĐÃ DUYỆT'. /generate-code · /generate-bdd ·",
+        "/generate-tech-docs · /map-testids CỐ Ý không nằm đây — chúng ghi thứ SINH RA ĐƯỢC từ",
+        "spec, không phải thứ người dùng đã duyệt bằng tay. Ba script migrate cũng không: chúng",
+        "là CLI, dry-run mặc định, không đi qua gate."
+      ],
+      "label_marker": "Checkpoint:",
+      "hard": [
+        { "cmd": "generate-prd",          "why": "ghi đè PRD đã có → mất changelog, ĐÁNH SỐ LẠI BR, phá @trace.business_rules trong mọi .feature đã sinh" },
+        { "cmd": "extend-prd",            "why": "sửa PRD đã DUYỆT" },
+        { "cmd": "refine-prd",            "why": "--resume áp findings trực tiếp vào PRD" },
+        { "cmd": "generate-architecture", "why": "ghi đè architecture.md đã verified_by một người thật" }
+      ],
+      "none": [
+        { "cmd": "review-code",       "why": "read-only" },
+        { "cmd": "validate-traces",   "why": "read-only (ghi trace-report.json + TSV status, không đụng spec/code)" },
+        { "cmd": "debug",             "why": "read-only" },
+        { "cmd": "review-context",    "why": "read-only (ghi findings vào .agent/review/)" },
+        { "cmd": "review-tech-docs",  "why": "read-only (ghi findings vào .agent/review/)" }
+      ]
+    },
+    "audit_invalidating_tags": {
+      "$comment": [
+        "TAG NÀO TRONG CODE, KHI ĐỔI, LÀM AUDIT HẾT TƯƠI (nợ #4 sau Wave 1).",
+        "",
+        "gate chứng minh 'report khớp SỔ', không chứng minh 'sổ khớp CODE' — việc đó cần",
+        "/validate-traces, một lệnh LLM không chạy được trong CI thường. Nên có lỗ: dev sửa",
+        "code mà không audit lại thì sổ+report vẫn khớp nhau, gate vẫn PASS, và mọi cờ 🔴 nói",
+        "về trạng thái TRƯỚC khi sửa. Job `require-fresh-audit` trong templates/ci/ bịt lỗ đó",
+        "bằng một PROXY: không verify được thì ĐÒI BẰNG CHỨNG có người vừa verify.",
+        "",
+        "VÌ SAO LÀ TAG CHỨ KHÔNG PHẢI `^src/`: bản đầu của job hỏi 'PR có sửa src/ không?' và",
+        "vì thế phải để TẮT mặc định — nó ĐO SAI THỨ. Framework có luật boundary-only tagging",
+        "(docs/02-concepts/traceability.md): chỉ Controller/Handler/Middleware/Steps mang tag;",
+        "Entity/Repository/DTO/Interface/Base KHÔNG. Nên `^src/` chặn PR chỉ sửa một DTO — một",
+        "file không mang lời khẳng định trace nào. Cái gì báo oan thì bị tắt, rồi mất luôn phần",
+        "thật sự cần chặn.",
+        "Câu hỏi đúng không phải 'PR có sửa src/?' mà 'PR có sửa thứ mà report đang KHẲNG ĐỊNH?'",
+        "— và report khẳng định qua tag, tag thì nhìn thấy trong diff.",
+        "",
+        "PHẠM VI: chỉ 7 tag là NGUỒN của 4 cờ chặn PR. Tag version (@trace.prd_version,",
+        "tech_doc_revision, design_spec_version) sinh ra cờ 🟠 — cờ đó cố ý không chặn, nên đổi",
+        "chúng không cần đòi audit lại.",
+        "",
+        "GIỚI HẠN ĐÃ BIẾT: đổi tên class (AuthService → AuthenticationService) không chạm dòng",
+        "tag ⇒ tag-diff bỏ lọt, dù cột `implemented_by` giờ trỏ vào tên không còn. Chấp nhận có",
+        "chủ ý: ca đó ít gặp hơn hẳn ca sửa-code-thường, và nó KHÔNG im lặng (lần /validate-traces",
+        "kế tiếp báo ngay). Còn báo oan thì xảy ra mỗi ngày và hậu quả là CỔNG BỊ TẮT — mất tất cả.",
+        "Biến thể chặt hơn ('PR chạm file nào CÓ chứa tag') ghi trong comment của template.",
+        "",
+        "self-check R10 canh templates/ci/trace-gate.yml có nhắc đủ 7 tag này. Tag đổi tên mà",
+        "file CI không biết ⇒ grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù im lặng."
+      ],
+      "ci_template": "templates/ci/trace-gate.yml",
+      "tags": [
+        { "tag": "@trace.implements",   "flags": ["ORPHANED", "TRACE_ORPHAN"] },
+        { "tag": "@trace.verifies",     "flags": ["ORPHANED", "TRACE_ORPHAN"] },
+        { "tag": "@trace.seam_port",    "flags": ["SEAM_UNWIRED"] },
+        { "tag": "@trace.seam_pending", "flags": ["SEAM_UNWIRED"] },
+        { "tag": "@trace.stub",         "flags": ["STUB_UNRESOLVED"] },
+        { "tag": "@trace.stub_owner",   "flags": ["STUB_UNRESOLVED"] },
+        { "tag": "@trace.stub_for",     "flags": ["STUB_UNRESOLVED"] }
+      ]
+    },
+    "blocking": [
+      {
+        "counter": "orphaned_count",
+        "issues_key": "orphaned",
+        "label_fields": ["sc_id", "platform"],
+        "why": "code + test còn trỏ vào scenario đã bị xoá khỏi .feature"
+      },
+      {
+        "counter": "trace_orphan_count",
+        "issues_key": "trace_orphan",
+        "label_fields": ["sc_id", "file"],
+        "why": "tag trong code trỏ vào SC-ID không tồn tại — không chỗ nào khác bắt được"
+      },
+      {
+        "counter": "seam_unwired_count",
+        "issues_key": "seam_unwired",
+        "label_fields": ["port", "consumer_uc"],
+        "why": "luồng ghép đang chạy vào stub thay vì hàng thật"
+      },
+      {
+        "counter": "stub_unresolved_count",
+        "issues_key": "stub_unresolved",
+        "label_fields": ["artifact", "consumer_uc"],
+        "why": "hàm rỗng chưa được lấp, nhưng caller đã gọi"
+      }
+    ],
+    "reconcile": {
+      "$comment": [
+        "Gate đọc trace-report.json — một file CÓ THỂ CŨ. Không kiểm tươi thì gate là sân khấu:",
+        "chạy /validate-traces một lần, commit report, rồi sửa spec/code tuỳ ý — CI đọc report cũ",
+        "và cho qua mãi. So sánh theo thời gian commit KHÔNG dùng được (report và code thường nằm",
+        "trong CÙNG một commit, nên mốc thời gian luôn 'cũ hơn'). Cách dùng được: đối chiếu report",
+        "với chính sổ TSV mà nó khai là đang mô tả. Bất biến dựa vào: /validate-traces Step 6 ghi",
+        "`status` trở lại TSV, nên NGAY SAU một lần chạy, TSV và report phải khớp.",
+        "hard = lệch thì FAIL (đếm số row là tuyệt đối, không nhập nhằng).",
+        "soft = lệch thì WARN (phụ thuộc quy ước đếm — vd ORPHANED được report biểu diễn bằng",
+        "boolean `orphaned` chứ không phải giá trị `status`, nên không ép cứng)."
+      ],
+      "hard": { "total_scs": "số row dữ liệu trong mọi TSV thuộc phạm vi report" },
+      "soft": {
+        "drift_count": "DRIFT",
+        "gap_count": "GAP",
+        "untracked_count": "UNTRACKED",
+        "orphaned_count": "ORPHANED"
+      },
+      "per_sc": {
+        "$comment": [
+          "G48 — đối chiếu TỪNG scenario thay vì chỉ tổng số. So tổng bỏ lọt ca thường gặp nhất",
+          "khi spec tiến hoá: một SC bị xoá + một SC được thêm trong cùng một lần → tổng KHÔNG",
+          "đổi → report cũ vẫn được coi là tươi. Khoá phải gồm platform: sc_id một mình không",
+          "định danh được scenario ('sc_id trùng số giữa các platform là 2 scenario khác nhau').",
+          "",
+          "Chuẩn hoá ORPHANED: JSON CỐ Ý chỉ có 4 giá trị status, và row ORPHANED xuất ra là",
+          "`status: DRIFT` + `orphaned: true` (validate-traces §Rules — để VS Code extension",
+          "switch trên status không rơi vào nhánh không khớp). Nên khi so với cột `status` của",
+          "TSV, phải quy đổi `orphaned:true` → ORPHANED TRƯỚC. Quy ước này ĐƯỢC GHI RÕ nên",
+          "status so được ở mức `hard`; nếu nó chỉ là suy đoán thì phải để `soft`.",
+          "",
+          "BACKWARD-COMPAT: report sinh bởi version trước G48 không có `platform`. Gate rơi về",
+          "so tổng số + in ⚠️ 'kiểm độ tươi đang ở mức yếu', KHÔNG fail — người dùng chưa chạy",
+          "lại /validate-traces không phải là lỗi của họ."
+        ],
+        "key_fields": ["sc_id", "platform"],
+        "compare": "status",
+        "orphaned_flag": "orphaned",
+        "orphaned_status": "ORPHANED"
+      }
+    }
+  },
+  "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"
+    }
+  ]
+}