@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/bin/trace-schema.json

@@ -1,1927 +1,2656 @@
-{
-  "$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",
-        "validate-traces"
-      ],
-      "read_by": [
-        "validate-traces",
-        "generate-bdd"
-      ]
-    },
-    {
-      "n": 5,
-      "name": "implemented_by",
-      "written_by": [
-        "generate-code",
-        "validate-traces"
-      ],
-      "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",
-        "validate-traces"
-      ],
-      "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. Cột này làm lời khẳng định kia thành sự thật.",
-        "",
-        "BỐN GIÁ TRỊ — G51 tách hai cái từng bị gộp:",
-        "  {path}      = đã route xong, đây là repo sở hữu",
-        "  unrouted    = CHƯA AI QUYẾT repo. Trạng thái HỢP LỆ và BÌNH THƯỜNG ở feature đầu tiên của",
-        "                một domain mới. Cờ 🟠 SERVICE_UNROUTED. KHÔNG chặn BDD, KHÔNG chặn PR.",
-        "  unresolved  = CONFIG SAI CẤU TRÚC (một entry vừa có path vừa có by_prd_slug, hoặc",
-        "                by_prd_slug lồng nhau). Đây là BUG cần sửa file, không phải trạng thái chờ.",
-        "  '—'         = single-service mode, không có khái niệm service",
-        "",
-        "VÌ SAO PHẢI TÁCH (G51): trước đó 'unresolved' mang CẢ HAI nghĩa nên cả hai chịu chung một",
-        "hình phạt — /generate-bdd DỪNG HẲN. Nhưng PRD/BDD là artifact NGHIỆP VỤ: PO biết domain",
-        "(auth, payment) và biết platform (web/app — người dùng làm việc đó ở đâu), nhưng KHÔNG biết",
-        "code sẽ nằm repo nào, và thường lúc đó CHƯA AI QUYẾT. Nên cổng đặt sai phase: nó chặn phase",
-        "KHÔNG CẦN biết, còn generate-code — phase BUỘC PHẢI biết mới ghi được file — thì không kiểm.",
-        "Ca bị đánh nặng nhất là feature ĐẦU TIÊN của một domain mới: chưa có mapping ⇒ PO bị chặn",
-        "bởi một quyết định thuộc architect, ở phase architect còn chưa vào.",
-        "",
-        "AI PHÂN GIẢI: validate-traces đọc lại services: mỗi lần chạy và nâng unrouted → path khi",
-        "mapping xuất hiện — giống cách nó đã làm với spec_ver. Architect thêm mapping ⇒ sổ TỰ LÀNH,",
-        "không sửa tay, KHÔNG phải chạy lại /generate-bdd. Vì thế validate-traces là producer thứ hai",
-        "của cột này, và đó là ngoại lệ CÓ CHỦ Ý với luật 'mỗi cột một chủ': nó không ghi giá trị mới,",
-        "nó chỉ phân giải một placeholder mà generate-bdd đã cố ý để lại."
-      ],
-      "written_by": [
-        "generate-bdd",
-        "validate-traces"
-      ],
-      "read_by": [
-        "validate-traces",
-        "generate-code"
-      ]
-    },
-    {
-      "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": {
-      "$comment": [
-        "PLATFORM = DELIVERY SURFACE, không phải tech stack. `webview` là surface thứ tư có thật:",
-        "một bundle web nhúng trong app native — không phải `web` (browser) và không phải `app`",
-        "(native). Nó có BDD riêng (tương tác khác), design-spec riêng, và repo riêng.",
-        "",
-        "VÌ SAO PHẢI THÊM (báo cáo từ project thật, v0.7.0): framework DẠY `webview` ở BỐN chỗ —",
-        "  templates/project-context.yaml   FORM C lấy webview mini-game làm ví dụ",
-        "  steps/context-loader.md 2c       ví dụ đầy đủ: bdd/webview/UC1.feature",
-        "  commands/setup-ai-first          prompt tự đưa ra `learning:webview:dap-chuot:phaser-game`",
-        "  modules/phaser-game              stack-profile có mục build cho webview",
-        "— rồi TỪ CHỐI nó ở tầng kiểm. lint-trace T5 là `err`, và validate-traces Step 1.0 DỪNG",
-        "NGAY khi lint exit 1 ⇒ project dùng đúng ví dụ của framework mất TOÀN BỘ audit.",
-        "",
-        "Đổi tên sổ KHÔNG phải đường ra: nó phá khoá routing `by_prd_slug`, lệch với",
-        "@trace.platform trong .feature, và gộp hai surface vào một sổ làm sc_id đụng nhau (mỗi",
-        "platform đánh SC từ 1).",
-        "",
-        "NỢ CÒN LẠI — danh sách này vẫn ĐÓNG: project cần `desktop`/`tv`/`mini-program`/`cli` sẽ",
-        "bị chặn y như vậy và phải chờ một bản release. Nguyên nhân gốc là `platform` được xử lý",
-        "như enum ĐÓNG trong contract nhưng MỌI code path sinh ra nó đều MỞ (setup-ai-first nhận",
-        "chuỗi bất kỳ · context-loader 2b đọc sub-key bất kỳ · generate-bdd ghi bdd/{platform}/",
-        "không kiểm gì). Cách sửa đúng là cho project TỰ KHAI thêm platform trong",
-        "project-context.yaml và để lint-trace đọc — giữ được tính năng bắt typo của T5 mà không",
-        "cần release cho từng surface mới. Đang hoãn có chủ ý, làm ở đợt sau."
-      ],
-      "values": [
-        "web",
-        "app",
-        "system",
-        "webview"
-      ],
-      "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_UNTRACKED_EDIT",
-        "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",
-        "LEDGER_BEHIND_CODE",
-        "SEAM_UNWIRED",
-        "STUB_UNRESOLVED",
-        "SEAM_PENDING",
-        "STUB_PENDING",
-        "SERVICE_UNROUTED"
-      ]
-    }
-  },
-  "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": "T13",
-          "why": "KHÔNG KIỂM ĐƯỢC hai điều kiện kia — thiếu binary `git`, hoặc sổ không nằm trong repo git nào. Đây là loại THỨ TƯ, khác cả ba loại còn lại: không phải 'đang có cái sai' (🔴), không phải 'nợ' (🟠), cũng không phải 'bảo vệ đang tắt' (T10/T11) — mà là 'KHÔNG BIẾT bảo vệ có bật hay không'. Trước T13, ca này làm G0 in ra `sổ được bảo vệ — 2/2 điều kiện`: một lời KHẲNG ĐỊNH trên bằng chứng chưa bao giờ được thu, tệ hơn im lặng (cùng hình dạng G55). Ca thường gặp nhất là CI dùng image tối giản — node:*-alpine và node:*-slim đều KHÔNG có git — tức chính môi trường mà cổng này tồn tại để chạy."
-        },
-        {
-          "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": "amend-prd",
-          "why": "SỬA TẠI CHỖ một AC/BR/UC đã duyệt — thao tác ghi DUY NHẤT trong framework được phép làm output KHÔNG phải superset của bản cũ"
-        },
-        {
-          "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_templates_comment": [
-    "MỖI file CI phải grep đủ 7 tag. Trước v0.7.2 chỉ có bản GitHub Actions được canh —",
-    "nên khi một team dịch sang GitLab, bản dịch KHÔNG được rule nào canh, và nếu nó tụt",
-    "lại sau schema thì grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù trong im lặng. Đúng",
-    "lỗi R10 tồn tại để chặn, chỉ ở một file khác loại. Thêm template CI mới thì THÊM VÀO",
-    "danh sách này ngay — R10 canh từng file."
-   ],
-   "ci_templates": [
-    "templates/ci/trace-gate.yml",
-    "templates/ci/trace-gate.gitlab-ci.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"
-          ]
-        }
-      ]
-    },
-    "report_root_keys": {
-     "$comment": [
-      "KEY Ở CẤP GỐC CỦA trace-report.json MÀ gate-trace ĐỌC (G57).",
-      "",
-      "VÌ SAO KHỐI NÀY TỒN TẠI: `report.domain` từng có 1 consumer (gate-trace, và nó CHẶN PR nếu",
-      "giá trị khác 'all') và 0 producer — validate-traces không có cờ nào để đặt nó. Năm chỗ trong",
-      "lệnh mô tả một 'domain argument' / 'domain filter' KHÔNG TỒN TẠI: ghi chú Gate ('target là",
-      "một tên domain hoặc UC-ID cụ thể từ $ARGUMENTS') · Step 1 đọc TSV 'khớp domain target' ·",
-      "schema report '<domain argument, or all if no filter>' · Step 8 'nếu có domain filter, chỉ",
-      "gồm các PRD đó trong prds[]' · dòng trace-history mang field domain.",
-      "Nên ô đó LUÔN ghi 'all', và phần kiểm của gate CHƯA BAO GIỜ chạy một lần nào.",
-      "",
-      "Đây ĐÚNG hình dạng R1 fail build vì nó ('field có consumer mà không có producer' — ca",
-      "@trace.sc_version: 3 consumer, 0 producer, sống qua nhiều version không ai bắt được). Nó sống",
-      "được vì R1 chỉ canh field trong SỔ TSV và tag trong CODE — không rule nào canh key ở cấp gốc",
-      "của BIÊN BẢN JSON. Cùng điểm mù mà R13 vừa bịt cho `spec_baseline`.",
-      "",
-      "Và ghi chú Gate còn tệ hơn im lặng: một agent đọc 'target là một tên domain hoặc UC-ID' sẽ",
-      "TIN rằng scoping hoạt động.",
-      "",
-      "R9(h) là phần 'máy canh': mỗi key phải CÓ MẶT trong skeleton JSON của validate-traces VÀ được",
-      "gate-trace đọc qua `report.{key}`. Cả hai đầu, không đầu nào được lửng."
-     ],
-     "keys": [
-      {
-       "key": "scope",
-       "shape": "{ kind: all | domain | prd | uc, value: string }",
-       "written_by": "validate-traces",
-       "read_by": "gate-trace",
-       "why": "Gate PHẢI chặn mọi biên bản phiến diện, không chỉ biên bản hẹp-theo-domain — xem $comment của scope_kinds cho ca false-green mà `domain` một mình không bắt được."
-      },
-      {
-       "key": "domain",
-       "shape": "tên domain, hoặc 'all'",
-       "written_by": "validate-traces",
-       "read_by": "gate-trace",
-       "why": "Giữ cho TƯƠNG THÍCH NGƯỢC: biên bản sinh trước G57 không có `scope`. Gate rơi về logic cũ + in ⚠️ 'kiểm độ phủ đang ở mức yếu' thay vì fail — người dùng chưa chạy lại /validate-traces không phải là lỗi của họ. Cùng khuôn backward-compat G48 đã dùng cho `platform`."
-      }
-     ],
-     "scope_kinds": {
-      "$comment": [
-       "BẪY FALSE-GREEN mà bản fix G57 sẽ TỰ TAY MỞ nếu không siết G2 cùng lúc.",
-       "",
-       "gate-trace bản cũ: `if (domain !== 'all') { others = domainsOnDisk().filter(≠domain);",
-       "if (others.length) fail }`. Trong repo MỘT domain, `others` là RỖNG ⇒ KHÔNG fail. Nên một",
-       "biên bản hẹp-theo-PRD (hoặc hẹp-theo-UC) trong repo một domain sẽ được gate nhận là 'toàn",
-       "bộ' — đúng cái 'cấp giấy xanh cho thứ chưa ai xem' mà chú thích của chính nó cảnh báo.",
-       "",
-       "Hiện tại vô hại vì không ai scope được. Nó BẬT NGAY khi scoping thành khả dụng. Nên điều",
-       "kiện đúng là: `scope.kind !== 'all'` ⇒ FAIL, KHÔNG ngoại lệ — không phụ thuộc vào việc trên",
-       "đĩa có bao nhiêu domain.",
-       "",
-       "Thêm cờ scope mà không siết G2 là biến cổng thành SÂN KHẤU — đúng cái G39 dựng lên để chống."
-      ],
-      "values": ["all", "domain", "prd", "uc"],
-      "gate_rule": "scope.kind !== 'all' ⇒ FAIL G2, không ngoại lệ",
-      "flags": [
-       { "flag": "--domain", "kind": "domain", "arg": "{domain}" },
-       { "flag": "--prd", "kind": "prd", "arg": "{TICKET-ID}" },
-       { "flag": "--uc", "kind": "uc", "arg": "{UC-ID}" }
-      ]
-     }
-    },
-    "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"
-      }
-    }
-  },
-  "changelog_row_contract": {
-    "$comment": [
-      "DÒNG CHANGELOG LÀ CONTRACT MÁY ĐỌC (G52 · G53 · G58).",
-      "",
-      "PRD phủ nhiều UC nhưng `Version` là MỘT scalar; tech-doc gộp cấp PRD phủ nhiều UC",
-      "nhưng `@trace.revision` cũng là một scalar. Nên sửa một UC làm MỌI UC lệch version.",
-      "Bộ lọc ở validate-traces Step 4/5 chống báo động oan bằng cách đọc dòng changelog để",
-      "biết lần bump đó ĐỤNG UC NÀO — nên dòng đó không phải văn xuôi cho người đọc, nó là",
-      "ĐẦU VÀO của một phép phân loại 🟠-vs-ⓘ.",
-      "",
-      "VÌ SAO CẦN KHỐI NÀY: trước đó contract này là contract DUY NHẤT có consumer ĐƯỢC CANH",
-      "(R1–R11 canh tên cột/field) mà KHÔNG producer nào được canh. Bốn lệnh ghi nó, ba hình",
-      "dạng khác nhau, không ai kiểm — và hỏng theo CẢ HAI hướng:",
-      "  G52 /review-context --fix ghi `Auto-fix: applied {N} findings` — 0 scope ⇒ 🟠 cho MỌI",
-      "      UC. Lệnh chạy thường xuyên nhất trong lane PO là lệnh gây nhiễu nhất; sau vài",
-      "      sprint PRD_DRIFT sáng thường trực và không ai đọc nữa — mất luôn cờ đúng.",
-      "  G53 /extend-prd ghi `sửa BR8` — nêu BR mà KHÔNG nêu UC sở hữu ⇒ UC đổi thật bị xếp ⓘ",
-      "      ⇒ rào của `--realign-prd-version` (chỉ chặn 🟠) MỞ CỬA ⇒ nhãn version bị dán lại",
-      "      trên một BR vừa đổi hành vi. Đây là hướng IM LẶNG, nặng hơn hướng ỒN.",
-      "  G58 /generate-tech-docs chỉ nói `thêm một row Changelog` — không format, không ví dụ.",
-      "      Chưa nổ vì comment trong template tình cờ đúng. Nợ chờ lệch.",
-      "",
-      "LỜI GIẢI ĐÃ TỒN TẠI TRONG CHÍNH FRAMEWORK: nhánh BDD của review-context Fix Mode",
-      "Phase 3 làm đúng chuẩn — bump `sc_version` theo TỪNG scenario bị đụng, liệt kê check",
-      "nào đổi thân scenario, và nói thẳng lý do (`bump vô cớ tạo DRIFT giả và làm cờ mất giá",
-      "trị`). Nhánh PRD ngay trên nó thì không. Khối này chỉ nâng cách làm đó lên thành",
-      "contract cho cả bốn producer.",
-      "",
-      "self-check R12 là phần `máy canh`: producer phải nhắc `scope_token`, consumer phải",
-      "nhắc `scope_token` + `neutral_marker` + `resolve_to_uc.anchor`. Marker được GHI mà",
-      "consumer không HIỂU thì tệ hơn không có marker — nó bị coi là văn xuôi và lọt im lặng."
-    ],
-    "scope_token": "{changelog_scope}",
-    "scope_grammar": "Mỗi mệnh đề mở đầu bằng ĐƠN VỊ SỞ HỮU rồi tới mô tả: `{UC-ID}: {mô tả}`. Nhiều mệnh đề ngăn bằng `;`. Nội dung không thuộc UC nào → `PRD-global: {mô tả}`. BR/AC luôn đi KÈM UC sở hữu (`UC3: sửa BR8`) và KHÔNG BAO GIỜ đứng một mình (`sửa BR8`) — consumer khớp theo UC, nên một BR đứng một mình làm UC sở hữu nó bị xếp ⓘ trong khi nội dung của nó vừa đổi.",
-    "ambiguous_fallback": "Không mệnh đề nào nêu được đơn vị sở hữu → consumer coi row là MƠ HỒ và gắn 🟠 cho MỌI UC (lưới an toàn: không suy đoán được thì quét rộng). Đây là hành vi ĐÚNG khi thiếu thông tin — nhưng là hành vi SAI khi producer CÓ thông tin mà không ghi.",
-    "neutral_marker": "[no-behavior]",
-    "neutral_semantics": "Hậu tố đặt sau một mệnh đề mà producer CHỨNG MINH ĐƯỢC là không đổi hành vi. Consumer: UC nêu trong mệnh đề có marker này KHÔNG bị 🟠 — nó ở lại ⓘ. Chỉ producer nào biết chính xác loại fix mình vừa áp mới được dùng; KHÔNG dùng cho người tự khai.",
-    "neutral_checks": [
-      { "check": "P4:skeleton", "why": "thêm section/metadata skeleton còn THIẾU — cấu trúc, không có nội dung nghiệp vụ nào mới" },
-      { "check": "P4:status-row", "why": "thêm `| **Status** | draft |` khi row vắng — giá trị mặc định, không phải quyết định nghiệp vụ" },
-      { "check": "P4:drop-empty-api-section", "why": "xoá section `Existing API Contract` RỖNG ở greenfield — xoá chỗ trống" }
-    ],
-    "not_neutral_checks": [
-      { "check": "P1:banned-term", "why": "term đó cũng nằm trong .feature đã sinh — BDD lỗi thời THẬT về thuật ngữ (B2/C4 sẽ bắt). Đổi từ trong PRD mà không nêu UC là bỏ sót, không phải trung tính." },
-      { "check": "P1:tech-jargon", "why": "auto-fix của nó là `diễn đạt lại` / `chuyển Design Spec` / `bỏ về Tech Docs` — VIẾT LẠI câu văn AC/BR, và nhánh 2/3 LẤY nội dung ra khỏi PRD. Không chứng minh được là trung tính." }
-    ],
-    "resolve_to_uc": {
-      "required": true,
-      "anchor": "BR/AC → UC sở hữu",
-      "how": "Chuẩn hoá tập bị ảnh hưởng VỀ UC trước khi so: BR → UC có BR đó trong bảng Business Rule (PRD §3); AC → UC có AC đó ở dòng `**AC liên quan:**`. Không có bước này thì phép thử `UC này có trong tập?` luôn FALSE cho một row chỉ nêu BR/AC ⇒ ⓘ sai (G53). Step 4 đã mở file PRD nên không phát sinh I/O.",
-      "fallback": "BR/AC không phân giải được về UC nào (ID đã bị xoá, hoặc PRD lệch cấu trúc) → coi row là MƠ HỒ (🟠 cho mọi UC), KHÔNG bỏ qua mệnh đề đó."
-    },
-    "producers": [
-      { "cmd": "refine-prd", "artifact": "PRD", "where": "Phase 3", "scope_source": "`uc_id` / `section` của các finding được chấp nhận" },
-      { "cmd": "extend-prd", "artifact": "PRD", "where": "Bước 6", "scope_source": "UC mới + UC SỞ HỮU mỗi BR/AC bị sửa (kết luận của Bước 3.2)" },
-      { "cmd": "amend-prd", "artifact": "PRD", "where": "Bước 5", "scope_source": "UC SỞ HỮU của mỗi ID mà PO khai tường minh ở Bước 1 (`amend_targets`)" },
-      { "cmd": "review-context", "artifact": "PRD", "where": "Fix Mode Phase 3", "scope_source": "`uc_id` của mọi finding `status: applied` (findings YAML — field bắt buộc)", "emits_neutral_marker": true, "why_emits": "nó là producer DUY NHẤT biết chính xác `check_id` của từng fix vừa áp, nên là producer duy nhất chứng minh được tính trung tính" },
-      { "cmd": "generate-tech-docs", "artifact": "tech-design.md", "where": "Bước 1 (APPEND) + §Sinh", "scope_source": "UC trong `input_features` của batch vừa thêm/sửa" }
-    ],
-    "consumers": [
-      { "cmd": "validate-traces", "where": "Step 4 (PRD) · Step 5 (tech-doc)", "use": "phân loại 🟠 DRIFT vs ⓘ STALE_REF theo từng UC" },
-      { "cmd": "generate-bdd", "where": "Version Check", "use": "khuyến nghị Y (cập nhật hẹp) vs F (gen lại toàn bộ)" }
-    ]
-  },
-  "spec_edit_detection": {
-    "$comment": [
-      "PHÁT HIỆN SỬA TÀI LIỆU NGOÀI ĐƯỜNG CHÍNH THỨC (G54, nửa sau).",
-      "",
-      "TOÀN BỘ lưới an toàn của framework so NHÃN VERSION, không so NỘI DUNG — không có một",
-      "content hash nào ở đâu. Nên một PRD bị sửa tay mà không bump version là điểm mù TUYỆT",
-      "ĐỐI: validate-traces thấy `PRD version == prd_version` ⇒ sạch · gate-trace thấy report",
-      "khớp sổ ⇒ PASS · require-fresh-audit thấy PR không chạm tag ⇒ không đòi audit. Cả ba",
-      "tầng xanh, và cả ba ĐÚNG theo định nghĩa của chính chúng.",
-      "",
-      "Và G54 không chỉ CHO PHÉP sửa tay — nó ĐẨY người dùng về đó: /generate-prd DỪNG HẲN trên",
-      "file đã có (§Guard: 'Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi Y/N') · /extend-prd chỉ",
-      "add-only · /refine-prd chỉ áp được finding do chính nó tìm ra. Trước /amend-prd, hành",
-      "vi hợp lý duy nhất còn lại LÀ mở file .md ra gõ. Thiết kế tự tạo ra con đường nó không",
-      "canh được.",
-      "",
-      "VÌ SAO KHÔNG DÙNG CONTENT HASH: git đã băm nội dung hộ rồi. Thêm một cột hash vào sổ",
-      "TSV là thêm một thứ ghi-tay-bởi-LLM (đúng lớp lỗi G38 mà lint-trace tồn tại để chống),",
-      "trong khi `git diff` trả lời chính xác cùng câu hỏi và không sai được.",
-      "",
-      "VÌ SAO KHÔNG NẰM TRONG `gate.blocking` — quyết định có chủ ý, không phải bỏ sót:",
-      "  1. `gate.blocking` có nghĩa HẸP là CODE ĐANG HỎNG, và R9(e) tồn tại để giữ ranh giới",
-      "     đó. Cờ này nói về SPEC; code có thể đang hoàn toàn đúng.",
-      "  2. Nợ tồn khi mới bật: mọi project đang chạy đều đã có PRD sửa tay. Một cờ chặn mới",
-      "     sẽ đỏ khắp nơi ở lần chạy đầu ⇒ người ta TẮT CỔNG ⇒ mất luôn 4 cờ 🔴 thật. Đó",
-      "     đúng là thất bại R9(e) được viết ra để chặn, chỉ đến bằng một cửa khác.",
-      "  3. Nó vẫn 🔴 trong REPORT và in mỗi lần chạy — đủ để thấy, không đủ để làm tắt cổng.",
-      "Team nào đã dọn sạch nợ tồn thì tự thêm counter này vào `gate.blocking`; một dòng.",
-      "",
-      "ĐƯỜNG RA TỰ LÀNH — cố ý KHÔNG có lệnh escape riêng: cách sửa đúng là bump version +",
-      "ghi một row changelog (tức chính việc /amend-prd làm hộ). Làm xong thì",
-      "`version != version_at_audit` ⇒ cờ tự tắt, và logic PRD_DRIFT bình thường tiếp quản.",
-      "Thêm một `--accept-edit` sẽ là thêm một đường DÁN NHÃN lên thay đổi chưa ai xem — đúng",
-      "cái sai mà rào của `--realign` tồn tại để chặn."
-    ],
-    "flag": "PRD_UNTRACKED_EDIT",
-    "detects": "nội dung file PRD đã đổi kể từ lần audit trước NHƯNG nhãn `Version` không đổi ⇒ có người sửa ngoài /generate-prd · /extend-prd · /amend-prd · /refine-prd · /review-context",
-    "baseline_fields": {
-      "$comment": "validate-traces GHI khối này vào trace-report.json mỗi lần chạy; lần chạy sau ĐỌC nó làm mốc. Thiếu nửa GHI thì cờ không bao giờ bật — R6/R7 chỉ canh được nửa BÁO CÁO (giá trị enum có xuất hiện · counter có trong summary), nên self-check R13 canh nửa này.",
-      "path": "spec_baseline",
-      "keys": ["prd_path", "sha_at_audit", "version_at_audit"]
-    },
-    "evidence": [
-      { "source": "git diff", "cmd": "git -C {specs repo} diff --name-only {sha_at_audit}..HEAD -- {prd_path}", "catches": "sửa đã commit" },
-      { "source": "git status", "cmd": "git -C {specs repo} status --porcelain -- {prd_path}", "catches": "sửa CHƯA commit — ca thường gặp nhất khi PO đang gõ" }
-    ],
-    "no_false_positive": "PO sửa VÀ bump version → `version != version_at_audit` → KHÔNG bật cờ. Chỉ đúng ca \"đổi nội dung, giữ nguyên nhãn\" mới bật.",
-    "degraded": "Không phải git repo, hoặc `sha_at_audit` không còn (history bị rewrite) → BỎ QUA check này và in một dòng ⚠️ nói rõ là đang mù, KHÔNG bịa cờ và KHÔNG im lặng.",
-    "written_by": ["validate-traces"],
-    "read_by": ["validate-traces", "sync"],
-    "$read_by_comment": [
-      "`sync` đọc mốc này để trả lời câu KHÁC với câu của diff pull-to-pull (G56).",
-      "Diff `{old_sha}..{new_sha}` trả lời \"đổi gì kể từ lần PULL trước\" — mốc đó RESET mỗi lần",
-      "pull. Pull thứ Hai, thứ Ba, thứ Tư mà không audit lần nào thì đến thứ Năm cái thấy được chỉ",
-      "là delta của MỘT ngày, không phải nợ đã tích. `sha_at_audit` trả lời \"đổi gì kể từ lần",
-      "AUDIT gần nhất\" — con số đó tích luỹ đúng, không bao giờ reset sai."
-    ]
-  },
-  "positive_assertion_guards": {
-    "$comment": [
-      "QUYỀN ĐƯỢC KHẲNG ĐỊNH `pass` (G55) — mệnh đề ĐỐI NGẪU của luật G28.",
-      "",
-      "rules/workflow.md §\"Làm mất hiệu lực ≠ ghi đè\" nói: ai làm một giá trị HẾT ĐÚNG thì BẮT",
-      "BUỘC hạ nó xuống. Luật đó đúng và được thực thi tốt (/generate-bdd, /generate-code,",
-      "/fix-bug đều làm). Nhưng nửa còn lại chưa được viết: AI KHẲNG ĐỊNH MỘT GIÁ TRỊ DƯƠNG THÌ",
-      "PHẢI KIỂM RẰNG MÌNH ĐƯỢC PHÉP KHẲNG ĐỊNH.",
-      "",
-      "Thiếu nửa sau nên chuỗi thành: hạ xuống → dựng lại → hạ xuống → dựng lại.",
-      "  1. PO đổi AC → /generate-bdd đặt status=DRIFT và HẠ dev_selftest→not_run, kèm cảnh báo",
-      "     \"{n} test của {sc_id} viết cho spec cũ — /dev-gen-test rà lại trước khi chạy\".",
-      "  2. Sáng sau dev chạy /dev-run-test (thói quen bình thường), CHƯA /generate-code, CHƯA",
-      "     /dev-gen-test. Test cũ + code cũ ⇒ xanh hết.",
-      "  3. /dev-run-test ghi dev_selftest=pass, dev_selftest_at=HÔM NAY.",
-      "Row giờ mang status=DRIFT + dev_selftest=pass với ngày hôm nay. Lệnh kế tiếp trong vòng",
-      "lặp dev BÌNH THƯỜNG vừa dựng lại đúng cái tín hiệu /generate-bdd hạ xuống.",
-      "",
-      "VÌ SAO `status` KHÔNG TRỰC GIAO Ở ĐÂY: hai file lệnh viết `dev_selftest`/`qc_status`",
-      "\"trực giao với status\". Trực giao về KẾT QUẢ CHẠY thì đúng. Nhưng ô này không mang nghĩa",
-      "\"test đã chạy và xanh\" — nó mang nghĩa \"scenario này đã được nghiệm thu theo spec HIỆN",
-      "TẠI\". Trên row DRIFT, nghĩa thứ nhất đúng và nghĩa thứ hai SAI. `pass` ở đó không phải",
-      "kết quả sai; nó là lời khẳng định sai về điều mà kết quả đó chứng minh.",
-      "",
-      "TIN XẤU LUÔN HỢP LỆ: `fail` VẪN được ghi trên row DRIFT. Đây là guard cho lời khẳng định",
-      "DƯƠNG, không phải lệnh \"bỏ qua kết quả khi DRIFT\". Test đỏ trên row DRIFT vẫn là thông",
-      "tin thật. Chỉ `pass` cần giấy phép.",
-      "",
-      "VÌ SAO CẦN CẢ HAI TẦNG:",
-      "  PA-1 (lệnh đọc status trước khi ghi) chặn NGUỒN.",
-      "  PA-2 (lint-trace T12) bắt TRẠNG THÁI, bất kể ai ghi — sổ sửa tay, sổ sinh bởi version",
-      "       framework cũ, hay một lệnh tương lai quên luật. T12 rẻ, xác định, chạy được trong",
-      "       CI mà không cần LLM.",
-      "T1–T8 kiểm HÌNH DẠNG TỪNG Ô (đủ 24 cột, giá trị trong vocabulary, ngày parse được) —",
-      "không rule nào kiểm NHẤT QUÁN GIỮA CÁC Ô. Nên `status=DRIFT` + `dev_selftest=pass` là một",
-      "sổ HOÀN TOÀN HỢP LỆ với cả 11 rule cũ. T12 là rule đầu tiên nhìn nhiều ô cùng lúc.",
-      "",
-      "LỖ ĐÃ BIẾT, chấp nhận có chủ ý: ca \"spec đổi theo hướng THÊM hành vi mới\". Sau khi",
-      "/generate-code bắt kịp, gen_ver=spec_ver ⇒ status=OK; test cũ vẫn PASS (chúng không sai,",
-      "chỉ KHÔNG PHỦ phần mới); test_count>0 nên không có GAP ⇒ bảng xanh trên một hành vi chưa",
-      "test lần nào. Đóng hẳn ca này cần một cột thứ 25 `test_spec_ver` — đổi contract + lint",
-      "binding + backward-compat với mọi sổ 24 cột đang tồn tại. Hoãn có chủ ý; guard này vẫn",
-      "thu hẹp đáng kể vì trong lúc row còn DRIFT thì dev_selftest bị giữ ở not_run, nên dev",
-      "buộc phải làm gì đó và đường đúng là /dev-gen-test."
-    ],
-    "lint_rule": "T12",
-    "blocked_when_status": ["DRIFT", "ORPHANED"],
-    "negative_always_written": "`fail` được ghi bình thường trên MỌI status — guard này chỉ chặn giá trị KHẲNG ĐỊNH. Chặn cả `fail` là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.",
-    "guards": [
-      {
-        "column": "dev_selftest",
-        "owner": "dev-run-test",
-        "positive_values": ["pass"],
-        "downgrade_to": "not_run",
-        "companion": "dev_selftest_at",
-        "companion_downgrade": "—",
-        "why": "trên row DRIFT, test cũ đang nghiệm thu một hành vi không còn tồn tại; trên row ORPHANED, scenario đã bị xoá khỏi .feature nên không còn gì để nghiệm thu"
-      },
-      {
-        "column": "qc_status",
-        "owner": "qc-run-test",
-        "positive_values": ["pass"],
-        "downgrade_to": "not_run",
-        "companion": "qc_run_at",
-        "companion_downgrade": "—",
-        "why": "đối xứng hoàn toàn với dev_selftest — `skip` KHÔNG bị chặn vì nó là giá trị trung tính, không phải lời khẳng định"
-      }
-    ]
-  },
-  "strict_use_check": {
-    "$comment": [
-      "R3 CANH 'CÓ NHẮC TÊN', KHÔNG CANH 'CÓ DÙNG'. Khối này siết đúng những field mà trả lời",
-      "sai gây hại IM LẶNG — và chỉ những field đó.",
-      "",
-      "R3 kiểm lời khai producer/consumer bằng cách tìm tên field trong file actor. Thấy → ✅.",
-      "Nhưng một file có thể chứa tên field vì nhiều lý do KHÔNG PHẢI 'đang dùng nó':",
-      "  1. câu tuyên bố CỐ Ý BỎ QUA — G55: /dev-run-test viết 'dev_selftest trực giao với",
-      "     `status`', tức chính câu đó khai rằng nó không dùng. R3 thấy chữ, đóng dấu ✅, và số",
-      "     lần đọc thật là 0. R3 xác nhận một contract bằng đúng câu văn đang phủ nhận contract.",
-      "  2. chú thích giải thích luật — R9(h): comment viết `scope.kind !== 'all'` trong khi code",
-      "     đã thành `false`.",
-      "  3. trích dẫn lịch sử — 'Bản cũ ghi cứng X'. Ca này HỢP LỆ và phải được phép tồn tại:",
-      "     framework cố ý giữ luật cũ để người sau biết luật mới chống cái gì.",
-      "  4. substring — `DRIFTED` chứa `DRIFT`. `mentions()` đã chặn được ca này (xem doc-comment",
-      "     của nó); ba ca trên thì không.",
-      "",
-      "VÌ SAO KHÔNG SIẾT R3 TOÀN CỤC — hai lý do, cái thứ hai là gốc:",
-      "  (a) R3 áp cho 42 tag + 24 cột × 33 lệnh. Siết toàn cục đẻ ra một loạt báo oan, và cái gì",
-      "      báo oan thì bị TẮT — rồi mất luôn phần R3 đang bắt thật (G5, G12, G13, G31, G32).",
-      "  (b) FILE LỆNH LÀ VĂN XUÔI, VÀ VĂN XUÔI CHÍNH LÀ CHƯƠNG TRÌNH. Với .js thì tách được code",
-      "      khỏi comment (`codeOf()`). Với .tmpl thì KHÔNG TỒN TẠI dấu hiệu cú pháp nào tách",
-      "      'câu chỉ dẫn dùng giá trị' khỏi 'câu nói về giá trị' — cả hai đều là câu tiếng Việt.",
-      "      Đây là tính chất của thiết kế framework, không sửa được bằng một rule.",
-      "",
-      "NÊN: opt-in, khoanh vùng. Cùng khuôn `positive_assertion_guards` và `checkpoint_levels` —",
-      "khai tường minh từng field nguy hiểm rồi để máy canh, thay vì một cú siết toàn cục.",
-      "",
-      "ANCHOR = DÒNG BẢNG MARKDOWN. Đây không phải heuristic tuỳ ý: framework này viết MỌI luật",
-      "rẽ nhánh bằng bảng — validate-traces Step 3 (`| Rule | Status | Điều kiện |`), gate.md Bước",
-      "3a (`| Mức | Lệnh nào |`), generate-code §Read Trace State (`| Status | Hành động |`),",
-      "dev-run-test §Guard (`| status của row | ghi gì |`). Một field được DÙNG để quyết định thì",
-      "nó xuất hiện trong bảng. Một field chỉ được NHẮC TỚI thì nằm trong câu văn.",
-      "Blockquote (`>`) bị loại: đó là chỗ của giải thích và trích dẫn lịch sử (ca 3 ở trên).",
-      "",
-      "KIỂM CHỨNG ANCHOR trên bản dev-run-test TRƯỚC G55: R3 PASS (lý do G55 sống được),",
-      "R15 FAIL. Và trên bản hiện tại: cả 8 field trong danh sách đều PASS — không báo oan."
-    ],
-    "anchor": "markdown_table_row",
-    "$anchor_note": "Dòng có ≥2 ký tự `|` sau khi trim, và KHÔNG bắt đầu bằng `>`. Khớp tên field theo ranh giới token (cùng hàm `mentions()` của R3) — nên `qc_status` KHÔNG thoả cho field `status`.",
-    "fields": [
-      {
-        "field": "status",
-        "actors": ["dev-run-test", "qc-run-test"],
-        "why": "G55 — đây là ca đã xảy ra thật. Không rẽ nhánh theo `status` thì hai lệnh ghi `pass` trên row `DRIFT`, tức dựng lại đúng tín hiệu `/generate-bdd` vừa hạ. Cờ NÓI DỐI, không phải cờ im lặng."
-      },
-      {
-        "field": "spec_ver",
-        "actors": ["generate-code"],
-        "why": "Một nửa của phép so sinh ra DRIFT. Không đọc thì `/generate-code` skip mọi row lỗi thời và không gì báo — spec đổi mà code không bao giờ theo."
-      },
-      {
-        "field": "gen_ver",
-        "actors": ["generate-code"],
-        "why": "Nửa còn lại. Thiếu một nửa thì phép so vô nghĩa, và nó vô nghĩa trong IM LẶNG."
-      },
-      {
-        "field": "implemented_by",
-        "actors": ["generate-code", "generate-bdd"],
-        "why": "Phân biệt UNTRACKED (chưa có code) với ORPHANED (code còn, spec mất). Đọc sai thì `/generate-bdd` xoá row của một scenario ĐÃ có code ⇒ method đó thành vô hình: không cờ nào, không report nào, mà vẫn được caller gọi."
-      },
-      {
-        "field": "test_count",
-        "actors": ["validate-traces"],
-        "why": "Quyết GAP vs OK. Không đọc thì mọi row có code đều thành OK ⇒ coverage báo xanh trên scenario chưa có một test nào."
-      }
-    ]
-  },
-  "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": "`integration`",
-      "reason": "Giá trị cột `fe_phase` là `integrated` (CÓ hậu tố -ed). Dạng không -ed chỉ thuộc về CỜ `--phase=integration`. Ghi sai vào sổ thì `--lint-trace` T3 báo lỗi enum, VÀ `fe_integrated` ở /validate-traces Step 7 đếm `integrated` nên counter mãi bằng 0 trong im lặng — đúng hình dạng G1 (cờ im lặng). R6 ĐÃ DỰ ĐOÁN ca này (comment của nó: 'G19 là ca này') và chỉ đúng công cụ là forbidden_patterns — nhưng chưa ai khai. Nó tái diễn thật ở 0.9.0: bốn chỗ trong hai lệnh ghi giá trị cột là dạng không -ed, và CHÍNH validate-traces.tmpl tự mâu thuẫn: một dòng bảo ghi dạng đó, dòng khác đếm `integrated`.",
-      "gap": "G19/G61"
-    },
-    {
-      "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"
-    }
-  ]
-}
+{
+  "$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",
+        "validate-traces"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-bdd"
+      ]
+    },
+    {
+      "n": 5,
+      "name": "implemented_by",
+      "written_by": [
+        "generate-code",
+        "validate-traces"
+      ],
+      "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/HỢP ĐỒNG TEST-ID vừa đổi): generate-bdd · generate-code · map-testids. Xem dev_selftest + rules/workflow.md 'Làm mất hiệu lực ≠ ghi đè'. map-testids vào danh sách này vì đổi một test-id trong §4.5.6 làm script QC bám id cũ HẾT ĐÚNG: nó định vị một element không còn mang id đó, nên `pass` cũ không còn nghĩa 'scenario đã được nghiệm thu theo spec hiện tại'. Cột 'Serves SC' của row chính là chỉ mục ngược để biết SC nào bị ảnh hưởng.",
+      "written_by": [
+        "qc-run-test",
+        "generate-bdd",
+        "generate-code",
+        "map-testids"
+      ],
+      "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 · map-testids. Xem qc_status.",
+      "written_by": [
+        "qc-run-test",
+        "generate-bdd",
+        "generate-code",
+        "map-testids"
+      ],
+      "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",
+      "$comment": [
+        "Chủ: review-tech-docs (set về @trace.revision mới khi duyệt) + generate-code.",
+        "BUMPER thứ ba: map-testids — CHỈ khi Step 5b làm ĐỔI giá trị một test-id ĐÃ CÓ trong §4.5.6.",
+        "",
+        "VÌ SAO (G64): §4.5.6 là hợp đồng mà /qc-design-test CHÉP CỨNG giá trị id vào .Test.md —",
+        "artifact bền, nằm lại. G63 dựng cơ chế phát hiện theo NHÃN: .Test.md stamp tech_doc_revision,",
+        "trạm 4-5 so với hiện tại. Nhưng map-testids sửa §4.5.6 mà KHÔNG bump nhãn ⇒ stamp KHÔNG NỔ",
+        "đúng ca quan trọng nhất — và đó là 'điểm mù tuyệt đối' rules/workflow.md đã nêu: 'mọi drift",
+        "detector so NHÃN VERSION, không so NỘI DUNG'.",
+        "",
+        "Đường vòng cũ — Next của map-testids là /review-tech-docs, lệnh đó CÓ bump — chỉ đúng KHI",
+        "người dùng đi theo Next. Mà Step 5b tồn tại chính vì ca 'sửa nhanh một id rồi đi tiếp'.",
+        "Dựa vào Next là dựa vào kỷ luật, không phải vào máy.",
+        "",
+        "THÊM ROW MỚI KHÔNG BUMP: chưa có .Test.md nào bám id mới nên không gì hết đúng. Cùng điều",
+        "kiện với việc Step 5b hạ qc_status."
+      ],
+      "written_by": [
+        "generate-code",
+        "review-tech-docs",
+        "map-testids"
+      ],
+      "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",
+        "validate-traces"
+      ],
+      "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. Cột này làm lời khẳng định kia thành sự thật.",
+        "",
+        "BỐN GIÁ TRỊ — G51 tách hai cái từng bị gộp:",
+        "  {path}      = đã route xong, đây là repo sở hữu",
+        "  unrouted    = CHƯA AI QUYẾT repo. Trạng thái HỢP LỆ và BÌNH THƯỜNG ở feature đầu tiên của",
+        "                một domain mới. Cờ 🟠 SERVICE_UNROUTED. KHÔNG chặn BDD, KHÔNG chặn PR.",
+        "  unresolved  = CONFIG SAI CẤU TRÚC (một entry vừa có path vừa có by_prd_slug, hoặc",
+        "                by_prd_slug lồng nhau). Đây là BUG cần sửa file, không phải trạng thái chờ.",
+        "  '—'         = single-service mode, không có khái niệm service",
+        "",
+        "VÌ SAO PHẢI TÁCH (G51): trước đó 'unresolved' mang CẢ HAI nghĩa nên cả hai chịu chung một",
+        "hình phạt — /generate-bdd DỪNG HẲN. Nhưng PRD/BDD là artifact NGHIỆP VỤ: PO biết domain",
+        "(auth, payment) và biết platform (web/app — người dùng làm việc đó ở đâu), nhưng KHÔNG biết",
+        "code sẽ nằm repo nào, và thường lúc đó CHƯA AI QUYẾT. Nên cổng đặt sai phase: nó chặn phase",
+        "KHÔNG CẦN biết, còn generate-code — phase BUỘC PHẢI biết mới ghi được file — thì không kiểm.",
+        "Ca bị đánh nặng nhất là feature ĐẦU TIÊN của một domain mới: chưa có mapping ⇒ PO bị chặn",
+        "bởi một quyết định thuộc architect, ở phase architect còn chưa vào.",
+        "",
+        "AI PHÂN GIẢI: validate-traces đọc lại services: mỗi lần chạy và nâng unrouted → path khi",
+        "mapping xuất hiện — giống cách nó đã làm với spec_ver. Architect thêm mapping ⇒ sổ TỰ LÀNH,",
+        "không sửa tay, KHÔNG phải chạy lại /generate-bdd. Vì thế validate-traces là producer thứ hai",
+        "của cột này, và đó là ngoại lệ CÓ CHỦ Ý với luật 'mỗi cột một chủ': nó không ghi giá trị mới,",
+        "nó chỉ phân giải một placeholder mà generate-bdd đã cố ý để lại."
+      ],
+      "written_by": [
+        "generate-bdd",
+        "validate-traces"
+      ],
+      "read_by": [
+        "validate-traces",
+        "generate-code"
+      ]
+    },
+    {
+      "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": {
+      "$comment": [
+        "PLATFORM = DELIVERY SURFACE, không phải tech stack. `webview` là surface thứ tư có thật:",
+        "một bundle web nhúng trong app native — không phải `web` (browser) và không phải `app`",
+        "(native). Nó có BDD riêng (tương tác khác), design-spec riêng, và repo riêng.",
+        "",
+        "VÌ SAO PHẢI THÊM (báo cáo từ project thật, v0.7.0): framework DẠY `webview` ở BỐN chỗ —",
+        "  templates/project-context.yaml   FORM C lấy webview mini-game làm ví dụ",
+        "  steps/context-loader.md 2c       ví dụ đầy đủ: bdd/webview/UC1.feature",
+        "  commands/setup-ai-first          prompt tự đưa ra `learning:webview:dap-chuot:phaser-game`",
+        "  modules/phaser-game              stack-profile có mục build cho webview",
+        "— rồi TỪ CHỐI nó ở tầng kiểm. lint-trace T5 là `err`, và validate-traces Step 1.0 DỪNG",
+        "NGAY khi lint exit 1 ⇒ project dùng đúng ví dụ của framework mất TOÀN BỘ audit.",
+        "",
+        "Đổi tên sổ KHÔNG phải đường ra: nó phá khoá routing `by_prd_slug`, lệch với",
+        "@trace.platform trong .feature, và gộp hai surface vào một sổ làm sc_id đụng nhau (mỗi",
+        "platform đánh SC từ 1).",
+        "",
+        "NỢ CÒN LẠI — danh sách này vẫn ĐÓNG: project cần `desktop`/`tv`/`mini-program`/`cli` sẽ",
+        "bị chặn y như vậy và phải chờ một bản release. Nguyên nhân gốc là `platform` được xử lý",
+        "như enum ĐÓNG trong contract nhưng MỌI code path sinh ra nó đều MỞ (setup-ai-first nhận",
+        "chuỗi bất kỳ · context-loader 2b đọc sub-key bất kỳ · generate-bdd ghi bdd/{platform}/",
+        "không kiểm gì). Cách sửa đúng là cho project TỰ KHAI thêm platform trong",
+        "project-context.yaml và để lint-trace đọc — giữ được tính năng bắt typo của T5 mà không",
+        "cần release cho từng surface mới. Đang hoãn có chủ ý, làm ở đợt sau."
+      ],
+      "values": [
+        "web",
+        "app",
+        "system",
+        "webview"
+      ],
+      "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_UNTRACKED_EDIT",
+        "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",
+        "LEDGER_BEHIND_CODE",
+        "SEAM_UNWIRED",
+        "STUB_UNRESOLVED",
+        "SEAM_PENDING",
+        "STUB_PENDING",
+        "SERVICE_UNROUTED"
+      ]
+    }
+  },
+  "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": "T13",
+          "why": "KHÔNG KIỂM ĐƯỢC hai điều kiện kia — thiếu binary `git`, hoặc sổ không nằm trong repo git nào. Đây là loại THỨ TƯ, khác cả ba loại còn lại: không phải 'đang có cái sai' (🔴), không phải 'nợ' (🟠), cũng không phải 'bảo vệ đang tắt' (T10/T11) — mà là 'KHÔNG BIẾT bảo vệ có bật hay không'. Trước T13, ca này làm G0 in ra `sổ được bảo vệ — 2/2 điều kiện`: một lời KHẲNG ĐỊNH trên bằng chứng chưa bao giờ được thu, tệ hơn im lặng (cùng hình dạng G55). Ca thường gặp nhất là CI dùng image tối giản — node:*-alpine và node:*-slim đều KHÔNG có git — tức chính môi trường mà cổng này tồn tại để chạy."
+        },
+        {
+          "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 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.",
+        "",
+        "/map-testids TỪNG ở danh sách miễn trừ trên, và ĐÓ LÀ SAI (G83). Lý do cũ: 'nó ghi thứ",
+        "SINH RA ĐƯỢC từ spec'. Dữ liệu thật phủ nhận tiền đề đó — 28/28 tech-doc của một dự án",
+        "đang chạy có §4.5.6 do SA VIẾT TAY, theo quy ước riêng (`uc{n}-z2-region`,",
+        "`uc1-z2-rank-avatar / uc1-z2-rank-name`) mà /map-testids KHÔNG tái tạo được: quy ước của",
+        "nó là {uc-lower}-{screen}-{element}-{type}. Và cả 28 doc đều THIẾU @trace.testid_attr,",
+        "tức lệnh này CHƯA TỪNG CHẠY ở đó — mọi bảng đang có đều do người viết.",
+        "",
+        "BÀI HỌC, ghi lại để không ai khôi phục miễn trừ cũ: 'sinh lại được' là tính chất của",
+        "CÔNG CỤ; 'bản đang có do ai viết' là sự thật về DỮ LIỆU. Chỉ cái thứ hai quyết định có",
+        "mất gì khi ghi đè. Khi miễn một lệnh khỏi cổng vì 'nó sinh lại được', hỏi tiếp: AI đã",
+        "sinh ra bản đang có?"
+      ],
+      "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": "amend-prd",
+          "why": "SỬA TẠI CHỖ một AC/BR/UC đã duyệt — thao tác ghi DUY NHẤT trong framework được phép làm output KHÔNG phải superset của bản cũ"
+        },
+        {
+          "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"
+        },
+        {
+          "cmd": "dev-gen-test",
+          "why": "ghi đè file test đã có → XOÁ bản sửa tay của dev (mock, fixture, expectation đã chỉnh) mà chính /dev-run-test bảo họ làm",
+          "$comment": [
+            "G84 — CÙNG KHUÔN G77, khác lane. Bốn trên bốn giống nhau:",
+            "                          /qc-run-test (G77)        /dev-gen-test (G84)",
+            "  ai sửa tay              QC — 'script-bug'         Dev — 'fix test (sai expectation)'",
+            "  luật chạy lại           ✅ đã thêm                 ❌ không có",
+            "  nhãn checkpoint         ✅ hard                    ❌ normal",
+            "  §Output khai file ghi   ✅ đã thêm                 ❌ chỉ khai sổ trace",
+            "",
+            "BẰNG CHỨNG dev SỬA TAY — chính /dev-run-test nói:",
+            "  :260  'Test fail → /fix-bug {TICKET_ID} (bug thật) hoặc FIX TEST (sai expectation)'",
+            "  :137  'TimeoutError | Test gọi LLM endpoint live | Thêm mock; kiểm tra test fixture'",
+            "",
+            "PHẠM VI: chỉ `hard` khi file test ĐÃ TỒN TẠI. Lần sinh đầu đi thẳng.",
+            "",
+            "KHÁC G77 MỘT ĐIỂM: trạm 5 QC có vòng đời CHẠY nhiều / SINH ít nên mặc định của nó là",
+            "'CHẠY, đừng sinh lại'. /dev-gen-test CHỈ SINH, không chạy gì — nên mặc định ở đây là",
+            "'sinh phần THIẾU, giữ phần ĐÃ CÓ'. Copy nguyên mặc định của G77 sang là copy nhầm ngữ cảnh.",
+            "",
+            "BÀI HỌC: vá một lỗ trong một LANE xong thì việc tiếp theo KHÔNG phải đi tiếp trong lane",
+            "đó — mà là hỏi 'lane nào khác có cấu trúc GƯƠNG?'. G77 vá lane QC; lane dev có cấu trúc",
+            "gương (sinh test → chạy → sửa → chạy lại) và lọt thêm một vòng nữa vì bản rà khuôn G67",
+            "khai phạm vi là '6 lệnh QC'."
+          ]
+        },
+        {
+          "cmd": "map-testids",
+          "why": "ghi đè §4.5.6 đã có → ĐỔI id hợp đồng mà SA viết tay, và kéo theo Step 5b hạ qc_status + bump tech_doc_revision cho một hợp đồng CHƯA HỎNG",
+          "$comment": [
+            "G83 — lệnh này TỪNG được miễn `hard` có chủ ý, xem $comment của checkpoint_levels.",
+            "Chỉ `hard` KHI §4.5.6 đã có row. Tech-doc chưa có bảng (brownfield thật) là ca lệnh này",
+            "SINH RA ĐỂ PHỤC VỤ — bắt CHECKPOINT cứng ở đó là ồn vô cớ.",
+            "",
+            "hard KHÔNG tự bảo toàn gì. Thứ thật sự giữ hợp đồng là luật reverse-document cho BẢNG ở",
+            "Step 2: id đã có trong bảng → DÙNG LẠI AS-IS, chỉ gán mới cho element chưa có row.",
+            "Luật đó vốn đã tồn tại CHO CODE ('nếu element đã có test-id → dùng lại as-is') mà không",
+            "có vế tương ứng cho bảng — trong khi BẢNG mới là hợp đồng, code là bên phải tuân theo."
+          ]
+        },
+        {
+          "cmd": "qc-run-test",
+          "why": "ghi đè script Python đã có → XOÁ bản sửa `script-bug` mà chính lệnh này bảo QC tự sửa bằng tay",
+          "$comment": [
+            "G77 — NẶNG HƠN G67, và lý do nằm ở TRIỆU CHỨNG.",
+            "",
+            "Vòng đời bình thường của trạm 5: sinh → chạy → đỏ → QC SỬA TAY → chạy lại. Bước cuối là",
+            "bước xoá. §Phân loại FAIL khai tường minh: `script-bug` ⇒ 'QC tự sửa. Không mở bug'.",
+            "",
+            "Triệu chứng sau khi mất bản sửa: 'tôi vừa sửa mà vẫn đỏ y hệt' — TRÙNG KHÍT với triệu",
+            "chứng của một bản sửa CHƯA ĐÚNG. Nên nó hỏng đúng vào lúc người ta đang sẵn sàng tin là",
+            "MÌNH sai, và vòng lặp sửa-lại có thể chạy nhiều lần trước khi ai nghi ngờ công cụ.",
+            "",
+            "LỖI GỐC: lệnh KHÔNG CÓ §Output — nó không khai mình ghi cái gì, ở đâu (đường dẫn chỉ nằm",
+            "trong modules/qc-playwright/stack-profile.yaml). Một lệnh không khai mình ghi gì thì không",
+            "ai nghĩ tới việc bảo vệ thứ nó ghi.",
+            "",
+            "MẶC ĐỊNH PHẢI ĐẢO: vòng đời trạm 5 là CHẠY nhiều, SINH ít. Mặc định cũ sinh lại mỗi lần",
+            "chạy, dù không có gì đổi."
+          ]
+        },
+        {
+          "cmd": "qc-design-test",
+          "why": "ghi đè *.Test.md đã qua cổng HITL /qc-review → mất `Status` đã duyệt, `Expected Result` đã sửa theo finding, dấu 🚫 Block vừa gỡ; và ĐÁNH SỐ LẠI TC_<FEATURE>_NNN mà REVIEW_<FEATURE>.md đang trỏ vào",
+          "$comment": [
+            "G78 — cùng khuôn G67/G77 nhưng 🟠, vì /qc-review chạy lại được và bắt lại phần lớn finding.",
+            "Cái mất là MỘT VÒNG REVIEW ĐẦY ĐỦ, không phải một sự thật sai — nhưng nó mất mà không ai",
+            "biết vì sao phải soát lại.",
+            "",
+            "Ô ít ai nghĩ tới: REVIEW_<FEATURE>.md nằm CẠNH file TC trong cùng thư mục và tham chiếu TC",
+            "THEO SỐ. Đánh số lại là làm cả biên bản soát trỏ sai — cùng hình dạng 🚫 Block ở G67, khác",
+            "cặp file.",
+            "",
+            "§duplicate-check KHÔNG phải lưới cho ca này: nó chống VIẾT TRÙNG, không chống GHI ĐÈ. Tên",
+            "nghe giống nhau đủ để tưởng đã có người lo."
+          ]
+        },
+        {
+          "cmd": "qc-analyze",
+          "why": "ghi đè DOC_GAP.md đã có → mất cột Trạng thái/Câu trả lời (PO điền TAY, KHÔNG sinh lại được), ĐÁNH SỐ LẠI GAP-ID, phá 🚫 Block trong mọi .Test.md đã sinh",
+          "$comment": [
+            "G67 — KHỚP BA TRÊN BA với lý do của generate-prd, và đó chính là lập luận:",
+            "  generate-prd → PRD          |  qc-analyze → DOC_GAP.md",
+            "  mất changelog               |  mất Trạng thái + Câu trả lời (PO điền tay)",
+            "  ĐÁNH SỐ LẠI BR              |  ĐÁNH SỐ LẠI GAP-UC{N}-{nnn}",
+            "  phá @trace.business_rules   |  phá 🚫 Block trong mọi .Test.md",
+            "      trong mọi .feature      |",
+            "",
+            "VÌ SAO TRƯỚC ĐÓ BỊ XẾP `normal`: danh sách hard là ALLOWLIST và mặc định là `normal`.",
+            "Schema tự thú điểm yếu đó ngay ở $comment của checkpoint_levels: 'thêm lệnh mới mà quên",
+            "thêm vào đó thì lại sai lần nữa'. Nó đã sai đúng như vậy. R11 KHÔNG bắt được vì R11 chỉ",
+            "kiểm nhãn-trong-file có khớp schema không — hai bên khớp nhau, cái sai nằm ở PHÂN LOẠI.",
+            "",
+            "PHẠM VI: chỉ `hard` KHI DOC_GAP.md ĐÃ TỒN TẠI. Lần chạy đầu không ghi đè gì; bắt CHECKPOINT",
+            "cứng ở đó là ồn vô cớ. Nhãn khai mức CAO NHẤT CÓ THỂ; phần rẽ nhánh nằm trong lệnh.",
+            "",
+            "hard KHÔNG TỰ BẢO TOÀN DỮ LIỆU — nó chỉ làm người ta dừng lại nhìn. Luật merge",
+            "'thêm-không-thay' trong chính lệnh mới là thứ giữ được hai ô của PO. Xem §Chạy lại của",
+            "commands/qc-analyze.tmpl.",
+            "",
+            "Đường lập lại từ trắng: --force (gate.bypass_flags), và report PHẢI khai số câu trả lời bị xoá."
+          ]
+        }
+      ],
+      "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/)"
+        }
+      ]
+    },
+    "bypass_flags": {
+      "$comment": [
+        "MỘT TÊN DUY NHẤT CHO VIỆC 'TÔI BIẾT ĐIỀU KIỆN NÀY, VẪN MUỐN CHẠY': --force.",
+        "",
+        "VÌ SAO CÓ KHỐI NÀY: trước nó, mỗi chỗ bỏ qua một điều kiện lại đặt một tên riêng —",
+        "--force (generate-code, bỏ guard status), --include-draft (qc-scope, bỏ chặn BDD nháp),",
+        "và exec-d0-b5 còn đang đề xuất --no-testid-contract 'theo đúng tinh thần --include-draft'.",
+        "Ba tên cho một hành vi, và cái thứ ba chưa kịp sinh ra đã thấy nó sẽ là cái thứ ba.",
+        "Người dùng phải nhớ mỗi lệnh một từ khác nhau để làm CÙNG một việc — và cái giá không",
+        "phải là gõ sai, mà là KHÔNG BIẾT rằng có đường ra, rồi đi sửa spec cho hợp lệ giả.",
+        "",
+        "BA ĐIỀU KHOẢN — thiếu cái nào thì --force thành 'ghi đè tất cả' và mất hết ý nghĩa:",
+        "",
+        "  (1) PHẠM VI KHAI TỪNG LỆNH, KHÔNG BAO GIỜ BAO TRÙM. Mỗi lệnh tự khai --force của nó",
+        "      bỏ qua ĐÚNG điều kiện nào; mọi điều kiện khác vẫn chặn. Tiền lệ đúng có sẵn:",
+        "      generate-code.tmpl §'--force có phạm vi HẸP — đây là ranh giới cứng, không phải",
+        "      khuyến nghị' … 'KHÔNG phải ghi đè tất cả'. Đó là khuôn, không phải ngoại lệ.",
+        "",
+        "  (2) PHẢI KHAI RA ĐÃ BỎ QUA GÌ. Report in một dòng cho MỖI điều kiện bị bỏ qua.",
+        "      Một cờ chung mà im lặng thì người dùng bỏ qua X cũng bỏ qua luôn Y, Z họ chưa",
+        "      từng biết có tồn tại. Tên chung là để DỄ NHỚ, không phải để DỄ MÙ.",
+        "",
+        "  (3) ARTIFACT PHẢI TỰ KHAI. Lần chạy có --force sinh ra file nào thì file đó mang một",
+        "      dòng nói nó dựa trên điều kiện bị bỏ qua. Cờ nằm ở dòng lệnh thì biến mất sau khi",
+        "      lệnh chạy xong; dấu nằm trong file thì đi cùng file tới người đọc sau.",
+        "",
+        "--force ≠ --yes. TRỤC KHÁC NHAU, KHÔNG BAO GIỜ GỘP:",
+        "  --yes   = 'tôi không ngồi đây để trả lời'      → bỏ qua CHECKPOINT (hỏi Y/N)",
+        "  --force = 'tôi biết điều kiện này, vẫn chạy'   → bỏ qua một ĐIỀU KIỆN NGHIỆP VỤ",
+        "Gộp là để một lần chạy headless âm thầm vượt mọi điều kiện — đúng thứ qc-scope §4 đã",
+        "từ chối khi nó tách --include-draft khỏi --yes. Đổi TÊN không đổi lập luận đó.",
+        "",
+        "KHÔNG PHẢI MỌI ĐIỀU KIỆN ĐỀU --force ĐƯỢC. Điều kiện thuộc lớp 'báo cáo sai' — bỏ qua",
+        "nó thì lệnh sinh ra một KHẲNG ĐỊNH sai chứ không phải một sản phẩm kém — là chặn cứng,",
+        "không cờ nào qua. Ví dụ: guard tiền đề của qc-design-test (G60) — thiếu DOC_GAP.md thì",
+        "TC bị gap chặn trông y hệt TC bình thường, và lỗi đi ra khỏi đội QC thành bug gửi PO.",
+        "Đó không phải 'tôi biết và chấp nhận', đó là 'tôi sẽ dán nhãn sai'.",
+        "",
+        "CÁC TÊN ĐÃ BỎ: --include-draft (đổi thành --force ở qc-scope, 2026-09-14). KHÔNG giữ",
+        "alias: hai tên cho một thứ chính là mầm drift mà khối này sinh ra để chặn."
+      ],
+      "canonical_name": "--force",
+      "never_merge_with": "--yes",
+      "required_clauses": [
+        "scope_declared_per_command",
+        "report_lists_what_was_bypassed",
+        "artifact_self_declares"
+      ],
+      "declared_by": [
+        {
+          "cmd": "generate-code",
+          "bypasses": "guard status ở §Read Trace State (row đang `OK` vẫn được gen lại)",
+          "never_bypasses": "mất member/tag của UC khác — luôn là lỗi chặn"
+        },
+        {
+          "cmd": "qc-scope",
+          "bypasses": "chặn BDD chưa `approved` — cả cổng `0/n` cấp PRD lẫn cổng target cấp UC",
+          "never_bypasses": "target không có trong `uc_list` (sai UC-ID / sai nền)"
+        }
+      ],
+      "hard_never_forceable": [
+        {
+          "cmd": "qc-design-test",
+          "condition": "guard tiền đề — thiếu REQUIREMENT_ANALYSIS.md / DOC_GAP.md / TEST_PLAN.md",
+          "why": "lớp 'báo cáo sai' (G60): thiếu DOC_GAP thì TC bị chặn mất dấu `🚫 Block`, lỗi đi ra khỏi đội QC thành bug gửi PO"
+        }
+      ]
+    },
+    "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_templates_comment": [
+        "MỖI file CI phải grep đủ 7 tag. Trước v0.7.2 chỉ có bản GitHub Actions được canh —",
+        "nên khi một team dịch sang GitLab, bản dịch KHÔNG được rule nào canh, và nếu nó tụt",
+        "lại sau schema thì grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù trong im lặng. Đúng",
+        "lỗi R10 tồn tại để chặn, chỉ ở một file khác loại. Thêm template CI mới thì THÊM VÀO",
+        "danh sách này ngay — R10 canh từng file."
+      ],
+      "ci_templates": [
+        "templates/ci/trace-gate.yml",
+        "templates/ci/trace-gate.gitlab-ci.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"
+          ]
+        }
+      ]
+    },
+    "report_root_keys": {
+      "$comment": [
+        "KEY Ở CẤP GỐC CỦA trace-report.json MÀ gate-trace ĐỌC (G57).",
+        "",
+        "VÌ SAO KHỐI NÀY TỒN TẠI: `report.domain` từng có 1 consumer (gate-trace, và nó CHẶN PR nếu",
+        "giá trị khác 'all') và 0 producer — validate-traces không có cờ nào để đặt nó. Năm chỗ trong",
+        "lệnh mô tả một 'domain argument' / 'domain filter' KHÔNG TỒN TẠI: ghi chú Gate ('target là",
+        "một tên domain hoặc UC-ID cụ thể từ $ARGUMENTS') · Step 1 đọc TSV 'khớp domain target' ·",
+        "schema report '<domain argument, or all if no filter>' · Step 8 'nếu có domain filter, chỉ",
+        "gồm các PRD đó trong prds[]' · dòng trace-history mang field domain.",
+        "Nên ô đó LUÔN ghi 'all', và phần kiểm của gate CHƯA BAO GIỜ chạy một lần nào.",
+        "",
+        "Đây ĐÚNG hình dạng R1 fail build vì nó ('field có consumer mà không có producer' — ca",
+        "@trace.sc_version: 3 consumer, 0 producer, sống qua nhiều version không ai bắt được). Nó sống",
+        "được vì R1 chỉ canh field trong SỔ TSV và tag trong CODE — không rule nào canh key ở cấp gốc",
+        "của BIÊN BẢN JSON. Cùng điểm mù mà R13 vừa bịt cho `spec_baseline`.",
+        "",
+        "Và ghi chú Gate còn tệ hơn im lặng: một agent đọc 'target là một tên domain hoặc UC-ID' sẽ",
+        "TIN rằng scoping hoạt động.",
+        "",
+        "R9(h) là phần 'máy canh': mỗi key phải CÓ MẶT trong skeleton JSON của validate-traces VÀ được",
+        "gate-trace đọc qua `report.{key}`. Cả hai đầu, không đầu nào được lửng."
+      ],
+      "keys": [
+        {
+          "key": "scope",
+          "shape": "{ kind: all | domain | prd | uc, value: string }",
+          "written_by": "validate-traces",
+          "read_by": "gate-trace",
+          "why": "Gate PHẢI chặn mọi biên bản phiến diện, không chỉ biên bản hẹp-theo-domain — xem $comment của scope_kinds cho ca false-green mà `domain` một mình không bắt được."
+        },
+        {
+          "key": "domain",
+          "shape": "tên domain, hoặc 'all'",
+          "written_by": "validate-traces",
+          "read_by": "gate-trace",
+          "why": "Giữ cho TƯƠNG THÍCH NGƯỢC: biên bản sinh trước G57 không có `scope`. Gate rơi về logic cũ + in ⚠️ 'kiểm độ phủ đang ở mức yếu' thay vì fail — người dùng chưa chạy lại /validate-traces không phải là lỗi của họ. Cùng khuôn backward-compat G48 đã dùng cho `platform`."
+        }
+      ],
+      "scope_kinds": {
+        "$comment": [
+          "BẪY FALSE-GREEN mà bản fix G57 sẽ TỰ TAY MỞ nếu không siết G2 cùng lúc.",
+          "",
+          "gate-trace bản cũ: `if (domain !== 'all') { others = domainsOnDisk().filter(≠domain);",
+          "if (others.length) fail }`. Trong repo MỘT domain, `others` là RỖNG ⇒ KHÔNG fail. Nên một",
+          "biên bản hẹp-theo-PRD (hoặc hẹp-theo-UC) trong repo một domain sẽ được gate nhận là 'toàn",
+          "bộ' — đúng cái 'cấp giấy xanh cho thứ chưa ai xem' mà chú thích của chính nó cảnh báo.",
+          "",
+          "Hiện tại vô hại vì không ai scope được. Nó BẬT NGAY khi scoping thành khả dụng. Nên điều",
+          "kiện đúng là: `scope.kind !== 'all'` ⇒ FAIL, KHÔNG ngoại lệ — không phụ thuộc vào việc trên",
+          "đĩa có bao nhiêu domain.",
+          "",
+          "Thêm cờ scope mà không siết G2 là biến cổng thành SÂN KHẤU — đúng cái G39 dựng lên để chống."
+        ],
+        "values": [
+          "all",
+          "domain",
+          "prd",
+          "uc"
+        ],
+        "gate_rule": "scope.kind !== 'all' ⇒ FAIL G2, không ngoại lệ",
+        "flags": [
+          {
+            "flag": "--domain",
+            "kind": "domain",
+            "arg": "{domain}"
+          },
+          {
+            "flag": "--prd",
+            "kind": "prd",
+            "arg": "{TICKET-ID}"
+          },
+          {
+            "flag": "--uc",
+            "kind": "uc",
+            "arg": "{UC-ID}"
+          }
+        ]
+      }
+    },
+    "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"
+      }
+    }
+  },
+  "changelog_row_contract": {
+    "$comment": [
+      "DÒNG CHANGELOG LÀ CONTRACT MÁY ĐỌC (G52 · G53 · G58).",
+      "",
+      "PRD phủ nhiều UC nhưng `Version` là MỘT scalar; tech-doc gộp cấp PRD phủ nhiều UC",
+      "nhưng `@trace.revision` cũng là một scalar. Nên sửa một UC làm MỌI UC lệch version.",
+      "Bộ lọc ở validate-traces Step 4/5 chống báo động oan bằng cách đọc dòng changelog để",
+      "biết lần bump đó ĐỤNG UC NÀO — nên dòng đó không phải văn xuôi cho người đọc, nó là",
+      "ĐẦU VÀO của một phép phân loại 🟠-vs-ⓘ.",
+      "",
+      "VÌ SAO CẦN KHỐI NÀY: trước đó contract này là contract DUY NHẤT có consumer ĐƯỢC CANH",
+      "(R1–R11 canh tên cột/field) mà KHÔNG producer nào được canh. Bốn lệnh ghi nó, ba hình",
+      "dạng khác nhau, không ai kiểm — và hỏng theo CẢ HAI hướng:",
+      "  G52 /review-context --fix ghi `Auto-fix: applied {N} findings` — 0 scope ⇒ 🟠 cho MỌI",
+      "      UC. Lệnh chạy thường xuyên nhất trong lane PO là lệnh gây nhiễu nhất; sau vài",
+      "      sprint PRD_DRIFT sáng thường trực và không ai đọc nữa — mất luôn cờ đúng.",
+      "  G53 /extend-prd ghi `sửa BR8` — nêu BR mà KHÔNG nêu UC sở hữu ⇒ UC đổi thật bị xếp ⓘ",
+      "      ⇒ rào của `--realign-prd-version` (chỉ chặn 🟠) MỞ CỬA ⇒ nhãn version bị dán lại",
+      "      trên một BR vừa đổi hành vi. Đây là hướng IM LẶNG, nặng hơn hướng ỒN.",
+      "  G58 /generate-tech-docs chỉ nói `thêm một row Changelog` — không format, không ví dụ.",
+      "      Chưa nổ vì comment trong template tình cờ đúng. Nợ chờ lệch.",
+      "",
+      "LỜI GIẢI ĐÃ TỒN TẠI TRONG CHÍNH FRAMEWORK: nhánh BDD của review-context Fix Mode",
+      "Phase 3 làm đúng chuẩn — bump `sc_version` theo TỪNG scenario bị đụng, liệt kê check",
+      "nào đổi thân scenario, và nói thẳng lý do (`bump vô cớ tạo DRIFT giả và làm cờ mất giá",
+      "trị`). Nhánh PRD ngay trên nó thì không. Khối này chỉ nâng cách làm đó lên thành",
+      "contract cho cả bốn producer.",
+      "",
+      "self-check R12 là phần `máy canh`: producer phải nhắc `scope_token`, consumer phải",
+      "nhắc `scope_token` + `neutral_marker` + `resolve_to_uc.anchor`. Marker được GHI mà",
+      "consumer không HIỂU thì tệ hơn không có marker — nó bị coi là văn xuôi và lọt im lặng."
+    ],
+    "scope_token": "{changelog_scope}",
+    "scope_grammar": "Mỗi mệnh đề mở đầu bằng ĐƠN VỊ SỞ HỮU rồi tới mô tả: `{UC-ID}: {mô tả}`. Nhiều mệnh đề ngăn bằng `;`. Nội dung không thuộc UC nào → `PRD-global: {mô tả}`. BR/AC luôn đi KÈM UC sở hữu (`UC3: sửa BR8`) và KHÔNG BAO GIỜ đứng một mình (`sửa BR8`) — consumer khớp theo UC, nên một BR đứng một mình làm UC sở hữu nó bị xếp ⓘ trong khi nội dung của nó vừa đổi.",
+    "ambiguous_fallback": "Không mệnh đề nào nêu được đơn vị sở hữu → consumer coi row là MƠ HỒ và gắn 🟠 cho MỌI UC (lưới an toàn: không suy đoán được thì quét rộng). Đây là hành vi ĐÚNG khi thiếu thông tin — nhưng là hành vi SAI khi producer CÓ thông tin mà không ghi.",
+    "neutral_marker": "[no-behavior]",
+    "neutral_semantics": "Hậu tố đặt sau một mệnh đề mà producer CHỨNG MINH ĐƯỢC là không đổi hành vi. Consumer: UC nêu trong mệnh đề có marker này KHÔNG bị 🟠 — nó ở lại ⓘ. Chỉ producer nào biết chính xác loại fix mình vừa áp mới được dùng; KHÔNG dùng cho người tự khai.",
+    "neutral_checks": [
+      {
+        "check": "P4:skeleton",
+        "why": "thêm section/metadata skeleton còn THIẾU — cấu trúc, không có nội dung nghiệp vụ nào mới"
+      },
+      {
+        "check": "P4:status-row",
+        "why": "thêm `| **Status** | draft |` khi row vắng — giá trị mặc định, không phải quyết định nghiệp vụ"
+      },
+      {
+        "check": "P4:drop-empty-api-section",
+        "why": "xoá section `Existing API Contract` RỖNG ở greenfield — xoá chỗ trống"
+      }
+    ],
+    "not_neutral_checks": [
+      {
+        "check": "P1:banned-term",
+        "why": "term đó cũng nằm trong .feature đã sinh — BDD lỗi thời THẬT về thuật ngữ (B2/C4 sẽ bắt). Đổi từ trong PRD mà không nêu UC là bỏ sót, không phải trung tính."
+      },
+      {
+        "check": "P1:tech-jargon",
+        "why": "auto-fix của nó là `diễn đạt lại` / `chuyển Design Spec` / `bỏ về Tech Docs` — VIẾT LẠI câu văn AC/BR, và nhánh 2/3 LẤY nội dung ra khỏi PRD. Không chứng minh được là trung tính."
+      }
+    ],
+    "resolve_to_uc": {
+      "required": true,
+      "anchor": "BR/AC → UC sở hữu",
+      "how": "Chuẩn hoá tập bị ảnh hưởng VỀ UC trước khi so: BR → UC có BR đó trong bảng Business Rule (PRD §3); AC → UC có AC đó ở dòng `**AC liên quan:**`. Không có bước này thì phép thử `UC này có trong tập?` luôn FALSE cho một row chỉ nêu BR/AC ⇒ ⓘ sai (G53). Step 4 đã mở file PRD nên không phát sinh I/O.",
+      "fallback": "BR/AC không phân giải được về UC nào (ID đã bị xoá, hoặc PRD lệch cấu trúc) → coi row là MƠ HỒ (🟠 cho mọi UC), KHÔNG bỏ qua mệnh đề đó."
+    },
+    "producers": [
+      {
+        "cmd": "refine-prd",
+        "artifact": "PRD",
+        "where": "Phase 3",
+        "scope_source": "`uc_id` / `section` của các finding được chấp nhận"
+      },
+      {
+        "cmd": "extend-prd",
+        "artifact": "PRD",
+        "where": "Bước 6",
+        "scope_source": "UC mới + UC SỞ HỮU mỗi BR/AC bị sửa (kết luận của Bước 3.2)"
+      },
+      {
+        "cmd": "amend-prd",
+        "artifact": "PRD",
+        "where": "Bước 5",
+        "scope_source": "UC SỞ HỮU của mỗi ID mà PO khai tường minh ở Bước 1 (`amend_targets`)"
+      },
+      {
+        "cmd": "review-context",
+        "artifact": "PRD",
+        "where": "Fix Mode Phase 3",
+        "scope_source": "`uc_id` của mọi finding `status: applied` (findings YAML — field bắt buộc)",
+        "emits_neutral_marker": true,
+        "why_emits": "nó là producer DUY NHẤT biết chính xác `check_id` của từng fix vừa áp, nên là producer duy nhất chứng minh được tính trung tính"
+      },
+      {
+        "cmd": "generate-tech-docs",
+        "artifact": "tech-design.md",
+        "where": "Bước 1 (APPEND) + §Sinh",
+        "scope_source": "UC trong `input_features` của batch vừa thêm/sửa"
+      }
+    ],
+    "consumers": [
+      {
+        "cmd": "validate-traces",
+        "where": "Step 4 (PRD) · Step 5 (tech-doc)",
+        "use": "phân loại 🟠 DRIFT vs ⓘ STALE_REF theo từng UC"
+      },
+      {
+        "cmd": "generate-bdd",
+        "where": "Version Check",
+        "use": "khuyến nghị Y (cập nhật hẹp) vs F (gen lại toàn bộ)"
+      }
+    ]
+  },
+  "spec_edit_detection": {
+    "$comment": [
+      "PHÁT HIỆN SỬA TÀI LIỆU NGOÀI ĐƯỜNG CHÍNH THỨC (G54, nửa sau).",
+      "",
+      "TOÀN BỘ lưới an toàn của framework so NHÃN VERSION, không so NỘI DUNG — không có một",
+      "content hash nào ở đâu. Nên một PRD bị sửa tay mà không bump version là điểm mù TUYỆT",
+      "ĐỐI: validate-traces thấy `PRD version == prd_version` ⇒ sạch · gate-trace thấy report",
+      "khớp sổ ⇒ PASS · require-fresh-audit thấy PR không chạm tag ⇒ không đòi audit. Cả ba",
+      "tầng xanh, và cả ba ĐÚNG theo định nghĩa của chính chúng.",
+      "",
+      "Và G54 không chỉ CHO PHÉP sửa tay — nó ĐẨY người dùng về đó: /generate-prd DỪNG HẲN trên",
+      "file đã có (§Guard: 'Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi Y/N') · /extend-prd chỉ",
+      "add-only · /refine-prd chỉ áp được finding do chính nó tìm ra. Trước /amend-prd, hành",
+      "vi hợp lý duy nhất còn lại LÀ mở file .md ra gõ. Thiết kế tự tạo ra con đường nó không",
+      "canh được.",
+      "",
+      "VÌ SAO KHÔNG DÙNG CONTENT HASH: git đã băm nội dung hộ rồi. Thêm một cột hash vào sổ",
+      "TSV là thêm một thứ ghi-tay-bởi-LLM (đúng lớp lỗi G38 mà lint-trace tồn tại để chống),",
+      "trong khi `git diff` trả lời chính xác cùng câu hỏi và không sai được.",
+      "",
+      "VÌ SAO KHÔNG NẰM TRONG `gate.blocking` — quyết định có chủ ý, không phải bỏ sót:",
+      "  1. `gate.blocking` có nghĩa HẸP là CODE ĐANG HỎNG, và R9(e) tồn tại để giữ ranh giới",
+      "     đó. Cờ này nói về SPEC; code có thể đang hoàn toàn đúng.",
+      "  2. Nợ tồn khi mới bật: mọi project đang chạy đều đã có PRD sửa tay. Một cờ chặn mới",
+      "     sẽ đỏ khắp nơi ở lần chạy đầu ⇒ người ta TẮT CỔNG ⇒ mất luôn 4 cờ 🔴 thật. Đó",
+      "     đúng là thất bại R9(e) được viết ra để chặn, chỉ đến bằng một cửa khác.",
+      "  3. Nó vẫn 🔴 trong REPORT và in mỗi lần chạy — đủ để thấy, không đủ để làm tắt cổng.",
+      "Team nào đã dọn sạch nợ tồn thì tự thêm counter này vào `gate.blocking`; một dòng.",
+      "",
+      "ĐƯỜNG RA TỰ LÀNH — cố ý KHÔNG có lệnh escape riêng: cách sửa đúng là bump version +",
+      "ghi một row changelog (tức chính việc /amend-prd làm hộ). Làm xong thì",
+      "`version != version_at_audit` ⇒ cờ tự tắt, và logic PRD_DRIFT bình thường tiếp quản.",
+      "Thêm một `--accept-edit` sẽ là thêm một đường DÁN NHÃN lên thay đổi chưa ai xem — đúng",
+      "cái sai mà rào của `--realign` tồn tại để chặn."
+    ],
+    "flag": "PRD_UNTRACKED_EDIT",
+    "detects": "nội dung file PRD đã đổi kể từ lần audit trước NHƯNG nhãn `Version` không đổi ⇒ có người sửa ngoài /generate-prd · /extend-prd · /amend-prd · /refine-prd · /review-context",
+    "baseline_fields": {
+      "$comment": "validate-traces GHI khối này vào trace-report.json mỗi lần chạy; lần chạy sau ĐỌC nó làm mốc. Thiếu nửa GHI thì cờ không bao giờ bật — R6/R7 chỉ canh được nửa BÁO CÁO (giá trị enum có xuất hiện · counter có trong summary), nên self-check R13 canh nửa này.",
+      "path": "spec_baseline",
+      "keys": [
+        "prd_path",
+        "sha_at_audit",
+        "version_at_audit"
+      ]
+    },
+    "evidence": [
+      {
+        "source": "git diff",
+        "cmd": "git -C {specs repo} diff --name-only {sha_at_audit}..HEAD -- {prd_path}",
+        "catches": "sửa đã commit"
+      },
+      {
+        "source": "git status",
+        "cmd": "git -C {specs repo} status --porcelain -- {prd_path}",
+        "catches": "sửa CHƯA commit — ca thường gặp nhất khi PO đang gõ"
+      }
+    ],
+    "no_false_positive": "PO sửa VÀ bump version → `version != version_at_audit` → KHÔNG bật cờ. Chỉ đúng ca \"đổi nội dung, giữ nguyên nhãn\" mới bật.",
+    "degraded": "Không phải git repo, hoặc `sha_at_audit` không còn (history bị rewrite) → BỎ QUA check này và in một dòng ⚠️ nói rõ là đang mù, KHÔNG bịa cờ và KHÔNG im lặng.",
+    "written_by": [
+      "validate-traces"
+    ],
+    "read_by": [
+      "validate-traces",
+      "sync"
+    ],
+    "$read_by_comment": [
+      "`sync` đọc mốc này để trả lời câu KHÁC với câu của diff pull-to-pull (G56).",
+      "Diff `{old_sha}..{new_sha}` trả lời \"đổi gì kể từ lần PULL trước\" — mốc đó RESET mỗi lần",
+      "pull. Pull thứ Hai, thứ Ba, thứ Tư mà không audit lần nào thì đến thứ Năm cái thấy được chỉ",
+      "là delta của MỘT ngày, không phải nợ đã tích. `sha_at_audit` trả lời \"đổi gì kể từ lần",
+      "AUDIT gần nhất\" — con số đó tích luỹ đúng, không bao giờ reset sai."
+    ]
+  },
+  "positive_assertion_guards": {
+    "$comment": [
+      "QUYỀN ĐƯỢC KHẲNG ĐỊNH `pass` (G55) — mệnh đề ĐỐI NGẪU của luật G28.",
+      "",
+      "rules/workflow.md §\"Làm mất hiệu lực ≠ ghi đè\" nói: ai làm một giá trị HẾT ĐÚNG thì BẮT",
+      "BUỘC hạ nó xuống. Luật đó đúng và được thực thi tốt (/generate-bdd, /generate-code,",
+      "/fix-bug đều làm). Nhưng nửa còn lại chưa được viết: AI KHẲNG ĐỊNH MỘT GIÁ TRỊ DƯƠNG THÌ",
+      "PHẢI KIỂM RẰNG MÌNH ĐƯỢC PHÉP KHẲNG ĐỊNH.",
+      "",
+      "Thiếu nửa sau nên chuỗi thành: hạ xuống → dựng lại → hạ xuống → dựng lại.",
+      "  1. PO đổi AC → /generate-bdd đặt status=DRIFT và HẠ dev_selftest→not_run, kèm cảnh báo",
+      "     \"{n} test của {sc_id} viết cho spec cũ — /dev-gen-test rà lại trước khi chạy\".",
+      "  2. Sáng sau dev chạy /dev-run-test (thói quen bình thường), CHƯA /generate-code, CHƯA",
+      "     /dev-gen-test. Test cũ + code cũ ⇒ xanh hết.",
+      "  3. /dev-run-test ghi dev_selftest=pass, dev_selftest_at=HÔM NAY.",
+      "Row giờ mang status=DRIFT + dev_selftest=pass với ngày hôm nay. Lệnh kế tiếp trong vòng",
+      "lặp dev BÌNH THƯỜNG vừa dựng lại đúng cái tín hiệu /generate-bdd hạ xuống.",
+      "",
+      "VÌ SAO `status` KHÔNG TRỰC GIAO Ở ĐÂY: hai file lệnh viết `dev_selftest`/`qc_status`",
+      "\"trực giao với status\". Trực giao về KẾT QUẢ CHẠY thì đúng. Nhưng ô này không mang nghĩa",
+      "\"test đã chạy và xanh\" — nó mang nghĩa \"scenario này đã được nghiệm thu theo spec HIỆN",
+      "TẠI\". Trên row DRIFT, nghĩa thứ nhất đúng và nghĩa thứ hai SAI. `pass` ở đó không phải",
+      "kết quả sai; nó là lời khẳng định sai về điều mà kết quả đó chứng minh.",
+      "",
+      "TIN XẤU LUÔN HỢP LỆ: `fail` VẪN được ghi trên row DRIFT. Đây là guard cho lời khẳng định",
+      "DƯƠNG, không phải lệnh \"bỏ qua kết quả khi DRIFT\". Test đỏ trên row DRIFT vẫn là thông",
+      "tin thật. Chỉ `pass` cần giấy phép.",
+      "",
+      "VÌ SAO CẦN CẢ HAI TẦNG:",
+      "  PA-1 (lệnh đọc status trước khi ghi) chặn NGUỒN.",
+      "  PA-2 (lint-trace T12) bắt TRẠNG THÁI, bất kể ai ghi — sổ sửa tay, sổ sinh bởi version",
+      "       framework cũ, hay một lệnh tương lai quên luật. T12 rẻ, xác định, chạy được trong",
+      "       CI mà không cần LLM.",
+      "T1–T8 kiểm HÌNH DẠNG TỪNG Ô (đủ 24 cột, giá trị trong vocabulary, ngày parse được) —",
+      "không rule nào kiểm NHẤT QUÁN GIỮA CÁC Ô. Nên `status=DRIFT` + `dev_selftest=pass` là một",
+      "sổ HOÀN TOÀN HỢP LỆ với cả 11 rule cũ. T12 là rule đầu tiên nhìn nhiều ô cùng lúc.",
+      "",
+      "LỖ ĐÃ BIẾT, chấp nhận có chủ ý: ca \"spec đổi theo hướng THÊM hành vi mới\". Sau khi",
+      "/generate-code bắt kịp, gen_ver=spec_ver ⇒ status=OK; test cũ vẫn PASS (chúng không sai,",
+      "chỉ KHÔNG PHỦ phần mới); test_count>0 nên không có GAP ⇒ bảng xanh trên một hành vi chưa",
+      "test lần nào. Đóng hẳn ca này cần một cột thứ 25 `test_spec_ver` — đổi contract + lint",
+      "binding + backward-compat với mọi sổ 24 cột đang tồn tại. Hoãn có chủ ý; guard này vẫn",
+      "thu hẹp đáng kể vì trong lúc row còn DRIFT thì dev_selftest bị giữ ở not_run, nên dev",
+      "buộc phải làm gì đó và đường đúng là /dev-gen-test."
+    ],
+    "lint_rule": "T12",
+    "blocked_when_status": [
+      "DRIFT",
+      "ORPHANED"
+    ],
+    "negative_always_written": "`fail` được ghi bình thường trên MỌI status — guard này chỉ chặn giá trị KHẲNG ĐỊNH. Chặn cả `fail` là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.",
+    "guards": [
+      {
+        "column": "dev_selftest",
+        "owner": "dev-run-test",
+        "positive_values": [
+          "pass"
+        ],
+        "downgrade_to": "not_run",
+        "companion": "dev_selftest_at",
+        "companion_downgrade": "—",
+        "why": "trên row DRIFT, test cũ đang nghiệm thu một hành vi không còn tồn tại; trên row ORPHANED, scenario đã bị xoá khỏi .feature nên không còn gì để nghiệm thu"
+      },
+      {
+        "column": "qc_status",
+        "owner": "qc-run-test",
+        "positive_values": [
+          "pass"
+        ],
+        "downgrade_to": "not_run",
+        "companion": "qc_run_at",
+        "companion_downgrade": "—",
+        "why": "đối xứng hoàn toàn với dev_selftest — `skip` KHÔNG bị chặn vì nó là giá trị trung tính, không phải lời khẳng định"
+      }
+    ]
+  },
+  "testid_contract": {
+    "$comment": [
+      "HỢP ĐỒNG TEST-ID FE↔QC — phần được MÁY canh.",
+      "",
+      "Contract gồm hai nửa, ở hai chỗ khác nhau trong CÙNG một tech-doc:",
+      "  @trace.testid_attr  (header, scope file) → TÊN THUỘC TÍNH, MỘT giá trị cho cả doc",
+      "  bảng §4.5.6          (thân, theo nền)     → GIÁ TRỊ test-id từng element, N dòng",
+      "Consumer per-UC lọc row của mình qua cột 'Serves SC (UC · SC)'.",
+      "",
+      "VÌ SAO CẦN CANH: trước khối này, bảng §4.5.6 được 3 lệnh ĐỌC (generate-code, qc-run-test,",
+      "qc-design-test) và 2 lệnh GHI (generate-tech-docs, map-testids) — mà 0 nơi kiểm. Luật chống",
+      "giẫm chân giữa hai người ghi là một CÂU VĂN XUÔI ở map-testids Step 5. Đây đúng hình dạng",
+      "đã gặp bốn lần trong loạt GAP: luật ĐÚNG, viết RÕ, và KHÔNG AI CANH (G1 · G28 · G41 · G55).",
+      "",
+      "PHẠM VI NEO VÀO SỰ TỒN TẠI CỦA HỢP ĐỒNG — điều khoản quan trọng nhất của khối này:",
+      "doc không có block §4.5 client thì KHÔNG kiểm gì. Dự án backend-only, hay dự án chưa từng",
+      "chạy /map-testids, phải im lặng hoàn toàn. Hai rule nói 'chỗ nào đã hứa thì phải giữ',",
+      "KHÔNG nói 'mọi chỗ đều phải có hợp đồng'. Thiếu điều khoản này thì mọi dự án đang chạy đỏ",
+      "ngay ngày nâng version, và việc đầu tiên người ta làm là thêm --warn-only vào CI.",
+      "",
+      "KHÔNG vào gate.blocking: đây là nợ cần thấy, không phải 'đang có cái sai' chặn PR.",
+      "Cùng nhóm với TECHDOC_DRIFT / BDD_DRIFT — 13/17 cờ audit hiện tại cũng không chặn."
+    ],
+    "artifact": "tech-design.md",
+    "header_field": "@trace.testid_attr",
+    "table_section": "4.5.6",
+    "serves_column": "Serves SC",
+    "lint_rules": [
+      {
+        "rule": "T15",
+        "level": "error",
+        "why": "Row §4.5.6 trỏ tới SC không tồn tại trong .feature. Consumer per-UC LỌC theo cột 'Serves SC' — trỏ vào SC đã bị gộp/xoá thì không khớp row nào, QC tưởng element không có test-id rồi đi dò DOM. Đây là phép so khớp chuỗi, không có chỗ cho suy luận, nên ERROR."
+      },
+      {
+        "rule": "T16",
+        "level": "warn+error",
+        "why": "Doc có §4.5 client mà header KHÔNG CÓ DÒNG @trace.testid_attr → WARN (G86): đó là doc LEGACY, sinh trước khi field vào template — trạng thái HỢP LỆ trong quy trình, y như placeholder. Lập luận giữ `error` ('QC đoán theo nền ⇒ trượt 100% locator TRONG IM LẶNG') đã HẾT ĐÚNG: qc-run-test và generate-code đều 'Cảnh báo mềm, KHÔNG im lặng hardcode'. Giữ error là dựng cổng thứ hai cho chuyện đã có người canh — và cổng đó CHẶN NHẦM NGƯỜI (30 doc của 2 domain khác chặn /validate-traces --prd FEAT-01-1). Cùng lập luận đã dùng cho T14. | Dòng CÓ MẶT mà giá trị RỖNG → vẫn ERROR: đó là 'ai đó xoá' khỏi một hợp đồng ĐÃ CHỐT. Dòng-không-tồn-tại vs dòng-rỗng là chỗ DUY NHẤT máy phân biệt được legacy với bị-xoá. | Còn placeholder → WARN."
+      },
+      {
+        "rule": "T17",
+        "level": "warn",
+        "needs": "--code",
+        "why": "Id đã khai ở §4.5.6 mà KHÔNG có trong code: FE chưa gắn, gắn sai giá trị, hoặc element đã đổi lúc implement. QC sẽ trượt locator đúng ở những id đó. WARN chứ không ERROR vì id đoán từ thiết kế không sống sót 100% — dev có thể gộp/tách element lúc implement, và đó là nợ cần thấy chứ không phải cái sai chặn người."
+      },
+      {
+        "rule": "T18",
+        "level": "warn",
+        "needs": "--code",
+        "why": "Id nằm trong code mà không có trong §4.5.6 nào: ai đó gắn ngoài hợp đồng — thường là /generate-code chạy khi bảng rỗng (người dùng chọn 'vẫn sinh với id TẠM'), hoặc sửa tay. Đây là lưới bắt phía sau cho quyết định đó: hợp đồng không còn đủ, và QC không biết những id này tồn tại. Chính vì có T18 mà /generate-code được phép hỏi rồi đi tiếp thay vì chặn cứng."
+      }
+    ],
+    "scope_flag": {
+      "flag": "--scope-prd",
+      "applies_to": [
+        "T15",
+        "T16",
+        "T19",
+        "T20"
+      ],
+      "never_applies_to": "T1–T14 (rule SỔ)",
+      "$comment": [
+        "G87 — rule TECH-DOC thu hẹp được theo PRD; rule SỔ thì KHÔNG.",
+        "",
+        "validate-traces:66 khai cố ý \"lint luôn chạy toàn bộ — sổ hỏng ở domain khác vẫn là sổ hỏng\".",
+        "ĐÚNG cho T1-T14: .tsv không regenerate được, và Step 3/6 của lệnh đó GHI NGƯỢC vào sổ.",
+        "T15/T16/T19/T20 canh TECH-DOC. Lý do kia không nối sang được, mà exit 1 thì chung một cửa —",
+        "nên lệnh CÓ SCOPE bị chặn bởi lỗi ở PRD NGOÀI SCOPE. Đã xảy ra thật.",
+        "",
+        "KHÔNG thu hẹp bằng --specs hẹp lại: lintTestidContract cần {domain}/{prd-slug} để tìm bdd/,",
+        "nên --specs trỏ thẳng feature-package làm parts.length<3 ⇒ continue ⇒ BỎ QUA IM LẶNG và báo",
+        "SẠCH trên tech-doc chưa từng được kiểm. Cách lách hiển nhiên nhất cho ra XANH GIẢ."
+      ]
+    }
+  },
+  "artifact_writers": {
+    "$comment": [
+      "AI GHI ARTIFACT NÀO, VÀ ARTIFACT ĐÓ CÓ PHẦN NGƯỜI NHẬP TAY KHÔNG (G74 · R18).",
+      "",
+      "VÌ SAO KHỐI NÀY TỒN TẠI — ĐẢO CHIỀU MỘT ALLOWLIST:",
+      "gate.checkpoint_levels là allowlist với mặc định `normal` (mức LỎNG NHẤT). Lệnh không khai",
+      "gì thì rơi vào đó. R11 duyệt TỪ SCHEMA RA FILE — nó chỉ kiểm lệnh ĐÃ được liệt kê, nên lệnh",
+      "CHƯA khai thì không vòng lặp nào chạm tới. Schema tự thú điểm yếu đó ngay ở $comment của",
+      "checkpoint_levels: 'thêm lệnh mới mà quên thêm vào đó thì lại sai lần nữa'. Nó đã sai đúng",
+      "như vậy BỐN lần: G67 (đã sửa) · G77 · G78 · G79.",
+      "",
+      "R18 duyệt CHIỀU NGƯỢC LẠI: mọi lệnh trong `enrolled` phải khai đủ, và khai",
+      "has_human_content:true thì BẮT BUỘC nằm trong checkpoint_levels.hard. Quên = BUILD ĐỎ,",
+      "thay vì quên = mở cửa.",
+      "",
+      "`why` LÀ BẮT BUỘC CẢ KHI has_human_content:false — đó chính là G79. /qc-plan và /qc-review",
+      "ghi đè AN TOÀN, nhưng không ai khai là an toàn, nên một ngoại lệ CÓ CHỦ Ý trông y hệt một chỗ",
+      "sót và sẽ bị copy đi. Bắt khai `why` biến im lặng thành một khẳng định KIỂM CHỨNG ĐƯỢC.",
+      "",
+      "PHẠM VI CÓ CHỦ Ý — `enrolled` hiện chỉ phủ 6 lệnh QC (phạm vi đợt rà GAPS-v5). 27 lệnh còn",
+      "lại nằm ở `pending_enrollment`: nợ được KHAI RA, không phải nợ vô hình. R18 không ép chúng,",
+      "nhưng danh sách đó phải RỖNG DẦN — và nó nằm trong schema nên không ai quên được nó tồn tại.",
+      "Khai một phạm vi hẹp và nói rõ là hẹp thì trung thực hơn là khai đầy đủ mà chưa rà."
+    ],
+    "enrolled": {
+      "qc-analyze": {
+        "writes": [
+          "DOC_GAP.md",
+          "REQUIREMENT_ANALYSIS.md",
+          "{refinement_dir}/{TICKET-ID}-qa-findings.yaml"
+        ],
+        "has_human_content": true,
+        "why": "PO điền TAY cột `Trạng thái` (Open/Answered) và cột `Câu trả lời` của DOC_GAP.md — không sinh lại được. Mã GAP-UC{N}-{nnn} còn bị .Test.md tham chiếu qua 🚫 Block."
+      },
+      "qc-run-test": {
+        "writes": [
+          "test Python pytest-playwright",
+          "Page Object"
+        ],
+        "has_human_content": true,
+        "why": "QC SỬA TAY chính các file này — §Phân loại FAIL khai tường minh: `script-bug` ⇒ 'QC tự sửa. Không mở bug'. Sinh lại là xoá công sửa lỗi, đúng lúc người ta chạy lại để kiểm bản sửa."
+      },
+      "qc-design-test": {
+        "writes": [
+          "test-cases/*.Test.md"
+        ],
+        "has_human_content": true,
+        "why": "File đi qua cổng HITL /qc-review: `Status` đổi sau review, `Expected Result` sửa theo finding, dấu 🚫 Block gỡ bằng tay — đều là kết luận của NGƯỜI, không suy lại từ spec. Và REVIEW_<FEATURE>.md đang trỏ vào số TC_<FEATURE>_NNN."
+      },
+      "qc-plan": {
+        "writes": [
+          "TEST_PLAN.md"
+        ],
+        "has_human_content": false,
+        "why": "questions-for-dev là danh sách GỬI ĐI; câu trả lời quay về qua DOC_GAP.md hoặc kênh chat, không ai điền ngược vào file này. Stamp phiên bản và cột Ready/Blocked đều do lệnh tự tính. KHAI LẠI NẾU về sau có ai điền tay vào đây."
+      },
+      "qc-review": {
+        "writes": [
+          "test-cases/REVIEW_<FEATURE>.md"
+        ],
+        "has_human_content": false,
+        "why": "Là BIÊN BẢN của một lần soát. Sinh lại = soát lại, đúng bản chất của nó — không có trạng thái nào tích luỹ qua các lần chạy."
+      },
+      "qc-report": {
+        "writes": [
+          "reports/<feature>/report.html",
+          "test-results/<nodeid>/trace.zip"
+        ],
+        "has_human_content": false,
+        "why": "Sinh hoàn toàn từ lần chạy gần nhất (pytest-html + Playwright Trace). Không có ô nào cho người điền."
+      },
+      "map-testids": {
+        "writes": [
+          "§4.5.6 Test Selectors (tech-doc gộp)",
+          "@trace.testid_attr (header)",
+          "figma-components catalog — Test-ID Forwarding",
+          "usage site FE (--from-code)"
+        ],
+        "has_human_content": true,
+        "why": "§4.5.6 là HỢP ĐỒNG do SA viết tay — 28/28 tech-doc thật dùng quy ước riêng (uc{n}-z2-region, ô đa-giá-trị) mà lệnh này KHÔNG tái tạo được (quy ước của nó: {uc-lower}-{screen}-{element}-{type}). Ghi đè là đổi hợp đồng đang được cả FE lẫn QC bám vào, mà không ai yêu cầu."
+      },
+      "dev-gen-test": {
+        "writes": [
+          "file unit/integration/E2E test theo module dev",
+          "sổ trace: test_count · test_classes · dev_selftest"
+        ],
+        "has_human_content": true,
+        "why": "Dev SỬA TAY chính các file test này — /dev-run-test:260 nói thẳng: \"Test fail → /fix-bug (bug thật) hoặc FIX TEST (sai expectation)\", và :137 \"Thêm mock; kiểm tra test fixture\". Cùng khuôn G77 ở lane QC, khác lane."
+      }
+    },
+    "pending_enrollment": {
+      "$comment": "Lệnh CÓ ghi file nhưng CHƯA rà xem có phần người nhập tay không. R18 không ép, nhưng danh sách này phải rỗng dần. Nợ được KHAI, không phải nợ vô hình.",
+      "cmds": [
+        "generate-prd",
+        "extend-prd",
+        "amend-prd",
+        "refine-prd",
+        "generate-bdd",
+        "generate-tech-docs",
+        "generate-design-spec",
+        "generate-architecture",
+        "generate-code",
+        "review-context",
+        "review-tech-docs",
+        "review-code",
+        "fix-bug",
+        "report-bug",
+        "propose-scenario",
+        "define-product",
+        "setup-ai-first",
+        "generate-spec-manifest",
+        "validate-traces",
+        "sync",
+        "learn",
+        "update-framework",
+        "dev-run-test",
+        "dev-smoke-test",
+        "debug"
+      ]
+    }
+  },
+  "testid_fourth_leg": {
+    "$comment": [
+      "CHÂN THỨ TƯ CỦA HỢP ĐỒNG TEST-ID: §4.5.6 ↔ *.Test.md (G64).",
+      "",
+      "testid_contract canh BA chân — ↔ .feature (T15) · ↔ header attr (T16) · ↔ code (T17/T18).",
+      "Chân thứ tư không ai canh, và nó là chân DUY NHẤT mà giá trị id bị CHÉP CỨNG vào một artifact",
+      "BỀN rồi nằm lại:",
+      "    generate-code  → bake vào code          → T17/T18 canh",
+      "    qc-run-test    → dựng locator LÚC CHẠY  → đọc bảng tươi, tự cứu",
+      "    qc-design-test → chép vào .Test.md      → KHÔNG AI CANH   ← đây",
+      "",
+      "KIỂU HỎNG LÀ 'NÓI DỐI', KHÔNG PHẢI 'IM LẶNG'. Lỗi CÓ hiện ra, nhưng ĐỘI LỐT thứ khác:",
+      "testid_contract đã ghi đúng chữ — 'test đỏ element not found TRÔNG Y HỆT bug sản phẩm'. Nên",
+      "/qc-report phân loại product-gap rồi in một /report-bug sẵn-chạy, và một lỗi hợp đồng NỘI BỘ",
+      "đi ra khỏi đội QC thành phiếu lỗi gửi PO.",
+      "",
+      "ĐẶT Ở TRẠM, KHÔNG Ở lint-trace. lint-trace quét theo cờ đường dẫn (--trace/--specs/--code) và",
+      "KHÔNG có --qc; thêm cờ thì khả thi (khác hẳn /validate-traces ở G63 — lệnh đó tự phân giải path",
+      "và không thể với tới), nhưng chỉ phủ khi người vận hành nhớ trỏ CẢ --specs LẪN --qc. Trạm 4-5",
+      "thì LUÔN đọc cả hai file, nên phủ 100% đường đi thật. Một rule lint T19 vẫn đáng làm sau, như",
+      "lớp CI — 'canh contract ≠ canh dữ liệu'.",
+      "",
+      "MỘT CHIỀU, KHÔNG HAI. Chiều ngược (§4.5.6 có id mà không TC nào nhắc) KHÔNG kiểm: không phải",
+      "element nào cũng cần một bước TC, nên kiểm chiều đó là ỒN. Đúng bất đối xứng T17/T18."
+    ],
+    "direction": "test_md_to_table",
+    "lint_rule": {
+      "rule": "T19",
+      "level": "warn",
+      "needs": "--qc",
+      "why": "LỚP CI cho chân thứ tư (G76). Guard ở /qc-review + /qc-run-test phủ 100% đường đi thật nhưng do LLM thực thi — nó không chặn được TRƯỚC khi merge. T19 nông hơn (chỉ so chuỗi) nhưng chạy trong CI. rules/workflow.md: 'Canh contract ≠ canh dữ liệu. Cần CẢ HAI' — đúng cặp self-check ↔ lint-trace. Bất đối xứng 3/4 (ba chân có lint, một chân không) là hình dạng G33: người đọc contract thấy bốn chân 'đã được canh' mà không phân biệt được chân nào chặn được ở CI.",
+      "skip_clauses": [
+        "Thiếu --qc → BỎ QUA CÓ TIẾNG. Không default: gốc artifact QC không đoán được (qc_dir là path QC duy nhất không remap theo spec_source), và 'quét sai chỗ còn tệ hơn không quét'.",
+        "Không có §4.5 client → im lặng HOÀN TOÀN. Điều khoản phạm vi của testid_contract; thiếu nó thì mọi dự án backend-only đỏ ngay ngày nâng version và việc đầu tiên người ta làm là thêm --warn-only vào CI.",
+        "--qc trỏ thư mục không có *.Test.md → BỎ QUA CÓ TIẾNG. Trỏ nhầm đường mà im lặng là xanh giả."
+      ]
+    },
+    "checked_by": [
+      {
+        "cmd": "qc-review",
+        "level": "warn"
+      },
+      {
+        "cmd": "qc-run-test",
+        "level": "warn",
+        "$note": "warn, KHÔNG chặn `pass` như qc_artifact_stamp. Id sai làm test ĐỎ, không làm test xanh giả — nên nó không thuộc lớp 'báo cáo sai'. Chặn ở đây là chặn nhầm loại."
+      }
+    ],
+    "filter": "Lọc row §4.5.6 theo cột 'Serves SC' khớp SC của UC này — id phục vụ UC khác không tính là 'lạ'.",
+    "scope_guard": "Không có block §4.5 client (dự án backend-only, hoặc chưa chạy /map-testids) → IM LẶNG HOÀN TOÀN. Cùng điều khoản phạm vi với testid_contract."
+  },
+  "qc_artifact_stamp": {
+    "$comment": [
+      "ARTIFACT QC PHẢI GHI MÌNH SINH RA TỪ BẢN NÀO — và trạm sau phải ĐỌC cái ghi đó (G63).",
+      "",
+      "VÌ SAO CẦN: /generate-bdd hạ qc_status → not_run khi spec đổi, rất đúng luật. Nhưng đó là",
+      "nửa 'KẾT QUẢ CHẠY hết hiệu lực'. Nửa còn thiếu là 'TÀI LIỆU THIẾT KẾ TEST hết khớp' — và",
+      "hai nửa dẫn tới HAI VIỆC KHÁC NHAU:",
+      "    qc_status = not_run   ⇒ CHẠY LẠI  (/qc-run-test)",
+      "    stamp lệch            ⇒ VIẾT LẠI  (/qc-design-test)",
+      "Thiếu nửa sau thì người ta thấy not_run và chạy lại một bộ TC lỗi thời — ra `pass`, và `pass`",
+      "đó HỢP LỆ theo mọi phép kiểm hiện có. rules/workflow.md: '`pass` … mang nghĩa scenario này",
+      "đã được nghiệm thu theo spec HIỆN TẠI'.",
+      "",
+      "VÌ SAO KHÔNG ĐẶT Ở /validate-traces — ĐIỀU KHOẢN QUAN TRỌNG NHẤT CỦA KHỐI NÀY:",
+      "qc_dir là path QC DUY NHẤT không được remap khi setup.spec_source được đặt (specs_dir,",
+      "tech_docs_dir, domain_knowledge_dir, trace_dir đều remap; qc_dir ở lại 'docs' của repo QC).",
+      "Nên ở chế độ umbrella — trace-mirror.md gọi là 'trường hợp phổ biến' — sổ trace và artifact",
+      "QC nằm ở HAI REPO KHÁC NHAU, và /validate-traces KHÔNG với tới artifact QC. Phép kiểm phải",
+      "nằm ở chính các trạm QC: chúng đã đọc cả artifact lẫn .feature, nên không phải vượt repo.",
+      "",
+      "VÌ SAO STAMP MÀ KHÔNG CÓ NGƯỜI ĐỌC THÌ VÔ NGHĨA: DOC_GAP.template.md ĐÃ CÓ cột 'Phiên bản'",
+      "trong bảng 'Tài liệu đầu vào đã đọc'. Nó được điền mỗi lần chạy. 0 CONSUMER. Đó là bài học",
+      "buoc/1-02 §B5: 'một con số trong báo cáo KHÔNG chứng minh có phép đo'. Thêm stamp mà không",
+      "thêm checker trong CÙNG một bản sửa là nhân bệnh đó lên bốn.",
+      "",
+      "NHÃN VERSION, KHÔNG PHẢI BĂM NỘI DUNG. rules/workflow.md tự nêu điểm mù: 'mọi drift detector",
+      "so NHÃN VERSION, không so NỘI DUNG'. Framework đã chọn chữa bằng cờ PRD_UNTRACKED_EDIT",
+      "(git diff), không bằng hash — '0 content hash trong toàn bộ codebase'. G63 đi cùng lựa chọn",
+      "đã có, không mở mặt trận thứ hai."
+    ],
+    "stamp_marker": "Nguồn & phiên bản",
+    "fields": {
+      "prd_version": {
+        "source": "| **Version** | của bảng metadata đầu PRD",
+        "probe": "\\|\\s*\\*\\*Version\\*\\*\\s*\\|",
+        "artifact": "prd"
+      },
+      "bdd_version": {
+        "source": "@trace.bdd_version của header .feature — GHI THEO TỪNG UC, không một số cho cả file",
+        "probe": "@trace\\.bdd_version\\s*:",
+        "artifact": "feature",
+        "$comment": "G85 — TRƯỚC ĐÓ khai là \"| **Version** | của header .feature\", và đó là KHÔNG THỂ ĐÚNG: .feature là GHERKIN, header của nó là khối comment # @trace.*, không có bảng Markdown nào. Đo thật: 0/278 file có dạng cũ, 276/278 có @trace.bdd_version. Mô tả cũ chép từ khuôn PRD — đúng cho PRD (Markdown có bảng), sai cho Gherkin. Bài học: một khuôn cho N nguồn chỉ đúng khi N nguồn cùng ĐỊNH DẠNG; \"đều có metadata đầu file\" KHÔNG đủ."
+      },
+      "tech_doc_revision": {
+        "source": "@trace.revision của header tech-doc gộp",
+        "probe": "@trace\\.revision\\s*:",
+        "artifact": "tech-design"
+      },
+      "design_spec_version": {
+        "source": "| **Version** | của bảng metadata đầu design-spec; \"—\" khi không có design-spec",
+        "probe": "\\|\\s*\\*\\*Version\\*\\*\\s*\\|",
+        "artifact": "design-spec"
+      },
+      "testid_attr": {
+        "source": "@trace.testid_attr của header tech-doc — chỉ .Test.md",
+        "probe": "@trace\\.testid_attr\\s*:",
+        "artifact": "tech-design",
+        "filled_by": "map-testids",
+        "$comment": [
+          "filled_by — trường này do MỘT LỆNH KHÁC điền sau, không phải phần bắt buộc của artifact.",
+          "Nên \"0/44 file có\" nghĩa là /map-testids CHƯA CHẠY (T16 đã kêu đúng 30 lần), KHÔNG phải mô tả sai.",
+          "Thiếu phân biệt này thì T20 báo oan ngay lần chạy đầu trên mọi dự án chưa chạy map-testids —",
+          "và một rule báo oan là một rule bị tắt."
+        ]
+      }
+    },
+    "artifacts": [
+      {
+        "file": "REQUIREMENT_ANALYSIS.md",
+        "written_by": "qc-analyze",
+        "stamps": [
+          "prd_version",
+          "bdd_version",
+          "tech_doc_revision",
+          "design_spec_version"
+        ]
+      },
+      {
+        "file": "DOC_GAP.md",
+        "written_by": "qc-analyze",
+        "stamps": [
+          "prd_version",
+          "bdd_version",
+          "tech_doc_revision",
+          "design_spec_version"
+        ]
+      },
+      {
+        "file": "TEST_PLAN.md",
+        "written_by": "qc-plan",
+        "stamps": [
+          "inherited"
+        ],
+        "$note": "qc-plan KHÔNG đọc spec trực tiếp — nó đọc output trạm 1. Nên nó CHÉP LẠI stamp của DOC_GAP, không tự đi lấy. Tự lấy là tạo hai nguồn cho một số rồi chúng lệch nhau."
+      },
+      {
+        "file": "test-cases/*.Test.md",
+        "written_by": "qc-design-test",
+        "stamps": [
+          "bdd_version",
+          "tech_doc_revision",
+          "testid_attr"
+        ]
+      }
+    ],
+    "checked_by": [
+      {
+        "cmd": "qc-plan",
+        "checks": [
+          "REQUIREMENT_ANALYSIS.md",
+          "DOC_GAP.md"
+        ],
+        "on_stale": "warn"
+      },
+      {
+        "cmd": "qc-design-test",
+        "checks": [
+          "REQUIREMENT_ANALYSIS.md",
+          "DOC_GAP.md",
+          "TEST_PLAN.md"
+        ],
+        "on_stale": "warn"
+      },
+      {
+        "cmd": "qc-review",
+        "checks": [
+          "test-cases/*.Test.md"
+        ],
+        "on_stale": "warn"
+      },
+      {
+        "cmd": "qc-run-test",
+        "checks": [
+          "test-cases/*.Test.md"
+        ],
+        "on_stale": "block_positive_assertion",
+        "$note": "KHÔNG chặn việc chạy. Chặn việc GHI `pass`: test xanh trên TC lỗi thời → qc_status = not_run. Nhập vào cơ chế positive_assertion_guards + lint T12 đã có (G55) — không phát minh cơ chế mới. `fail` VẪN ghi bình thường: đây là guard chống BÁO CÁO SAI, không phải guard CHE TIN XẤU."
+      }
+    ],
+    "severity_rationale": {
+      "warn": "Trạm 2-3 cùng họ TECHDOC_DRIFT / BDD_DRIFT — 13/17 cờ audit không chặn. Thiết kế TC trên bản hơi cũ vẫn ra sản phẩm dùng được; chặn ở đây là ồn.",
+      "block_positive_assertion": "Trạm 5 thuộc lớp BÁO CÁO SAI: ghi `pass` từ TC lỗi thời là khẳng định 'đã nghiệm thu theo spec hiện tại' cho một thứ chưa từng được kiểm theo spec hiện tại."
+    },
+    "backward_compat": {
+      "no_stamp_found": "warn_missing_not_stale",
+      "$comment": [
+        "Artifact sinh TRƯỚC khi có khối này thì KHÔNG có stamp. Phải báo 'chưa có stamp — chạy",
+        "lại để đóng dấu', KHÔNG báo 'lệch'. Cùng điều khoản với testid_contract: 'doc không có",
+        "block §4.5 client thì KHÔNG kiểm gì… thiếu điều khoản này thì mọi dự án đang chạy đỏ ngay",
+        "ngày nâng version, và việc đầu tiên người ta làm là thêm --warn-only vào CI'."
+      ]
+    },
+    "per_uc_rule": {
+      "$comment": [
+        "bdd_version GHI THEO TỪNG UC. DOC_GAP.md và REQUIREMENT_ANALYSIS.md phủ CẢ PRD, mà mỗi UC",
+        "là một file .feature riêng với version riêng — một số duy nhất cho cả file sẽ SAI cho n-1 UC.",
+        "Và phép so cũng theo từng UC: bump bdd_version của UC2 thì /qc-design-test {UC1} phải IM LẶNG.",
+        "Báo động oan ở đây đắt hơn bình thường vì trạm 3 chạy per-UC, nhiều lần cho mỗi PRD."
+      ]
+    },
+    "missing_source": {
+      "rule": "ghi \"—\" VÀ in một dòng ⚠️ — không bỏ trống, không đoán",
+      "$comment": [
+        "Đo thật: 2/278 .feature thiếu @trace.bdd_version. qc-stamp trước đó KHÔNG có ca này.",
+        "Cùng khuôn đã dùng cho @trace.testid_attr: \"Không đọc được → ghi — (thiếu …), ĐỪNG bỏ trống,",
+        "ĐỪNG tự đoán\". Bỏ trống im lặng thì \"không lấy được\" trông y hệt \"artifact cũ chưa có stamp\",",
+        "mà backward_compat bảo ĐỪNG báo lệch ở ca đó — điều khoản tương thích ngược sẽ NUỐT LUÔN lỗi."
+      ]
+    },
+    "lint_rule": {
+      "rule": "T20",
+      "level": "warn",
+      "needs": "--specs",
+      "why": "G85 — mọi fields.*.probe phải TÌM ĐƯỢC trong ít nhất một artifact thật. Mô tả \"lấy X từ Y\" đi qua mọi phép kiểm vì chưa ai đi lấy thử: kiểm chỉ dẫn CÓ MẶT khác kiểm nó DÙNG ĐƯỢC. Rule này phải đỏ trên mô tả CŨ của bdd_version — bắt được lỗi ĐÃ BIẾT, không chỉ lỗi tương lai."
+    }
+  },
+  "strict_use_check": {
+    "$comment": [
+      "R3 CANH 'CÓ NHẮC TÊN', KHÔNG CANH 'CÓ DÙNG'. Khối này siết đúng những field mà trả lời",
+      "sai gây hại IM LẶNG — và chỉ những field đó.",
+      "",
+      "R3 kiểm lời khai producer/consumer bằng cách tìm tên field trong file actor. Thấy → ✅.",
+      "Nhưng một file có thể chứa tên field vì nhiều lý do KHÔNG PHẢI 'đang dùng nó':",
+      "  1. câu tuyên bố CỐ Ý BỎ QUA — G55: /dev-run-test viết 'dev_selftest trực giao với",
+      "     `status`', tức chính câu đó khai rằng nó không dùng. R3 thấy chữ, đóng dấu ✅, và số",
+      "     lần đọc thật là 0. R3 xác nhận một contract bằng đúng câu văn đang phủ nhận contract.",
+      "  2. chú thích giải thích luật — R9(h): comment viết `scope.kind !== 'all'` trong khi code",
+      "     đã thành `false`.",
+      "  3. trích dẫn lịch sử — 'Bản cũ ghi cứng X'. Ca này HỢP LỆ và phải được phép tồn tại:",
+      "     framework cố ý giữ luật cũ để người sau biết luật mới chống cái gì.",
+      "  4. substring — `DRIFTED` chứa `DRIFT`. `mentions()` đã chặn được ca này (xem doc-comment",
+      "     của nó); ba ca trên thì không.",
+      "",
+      "VÌ SAO KHÔNG SIẾT R3 TOÀN CỤC — hai lý do, cái thứ hai là gốc:",
+      "  (a) R3 áp cho 42 tag + 24 cột × 33 lệnh. Siết toàn cục đẻ ra một loạt báo oan, và cái gì",
+      "      báo oan thì bị TẮT — rồi mất luôn phần R3 đang bắt thật (G5, G12, G13, G31, G32).",
+      "  (b) FILE LỆNH LÀ VĂN XUÔI, VÀ VĂN XUÔI CHÍNH LÀ CHƯƠNG TRÌNH. Với .js thì tách được code",
+      "      khỏi comment (`codeOf()`). Với .tmpl thì KHÔNG TỒN TẠI dấu hiệu cú pháp nào tách",
+      "      'câu chỉ dẫn dùng giá trị' khỏi 'câu nói về giá trị' — cả hai đều là câu tiếng Việt.",
+      "      Đây là tính chất của thiết kế framework, không sửa được bằng một rule.",
+      "",
+      "NÊN: opt-in, khoanh vùng. Cùng khuôn `positive_assertion_guards` và `checkpoint_levels` —",
+      "khai tường minh từng field nguy hiểm rồi để máy canh, thay vì một cú siết toàn cục.",
+      "",
+      "ANCHOR = DÒNG BẢNG MARKDOWN. Đây không phải heuristic tuỳ ý: framework này viết MỌI luật",
+      "rẽ nhánh bằng bảng — validate-traces Step 3 (`| Rule | Status | Điều kiện |`), gate.md Bước",
+      "3a (`| Mức | Lệnh nào |`), generate-code §Read Trace State (`| Status | Hành động |`),",
+      "dev-run-test §Guard (`| status của row | ghi gì |`). Một field được DÙNG để quyết định thì",
+      "nó xuất hiện trong bảng. Một field chỉ được NHẮC TỚI thì nằm trong câu văn.",
+      "Blockquote (`>`) bị loại: đó là chỗ của giải thích và trích dẫn lịch sử (ca 3 ở trên).",
+      "",
+      "KIỂM CHỨNG ANCHOR trên bản dev-run-test TRƯỚC G55: R3 PASS (lý do G55 sống được),",
+      "R15 FAIL. Và trên bản hiện tại: cả 8 field trong danh sách đều PASS — không báo oan."
+    ],
+    "anchor": "markdown_table_row",
+    "$anchor_note": "Dòng có ≥2 ký tự `|` sau khi trim, và KHÔNG bắt đầu bằng `>`. Khớp tên field theo ranh giới token (cùng hàm `mentions()` của R3) — nên `qc_status` KHÔNG thoả cho field `status`.",
+    "fields": [
+      {
+        "field": "status",
+        "actors": [
+          "dev-run-test",
+          "qc-run-test"
+        ],
+        "why": "G55 — đây là ca đã xảy ra thật. Không rẽ nhánh theo `status` thì hai lệnh ghi `pass` trên row `DRIFT`, tức dựng lại đúng tín hiệu `/generate-bdd` vừa hạ. Cờ NÓI DỐI, không phải cờ im lặng."
+      },
+      {
+        "field": "spec_ver",
+        "actors": [
+          "generate-code"
+        ],
+        "why": "Một nửa của phép so sinh ra DRIFT. Không đọc thì `/generate-code` skip mọi row lỗi thời và không gì báo — spec đổi mà code không bao giờ theo."
+      },
+      {
+        "field": "gen_ver",
+        "actors": [
+          "generate-code"
+        ],
+        "why": "Nửa còn lại. Thiếu một nửa thì phép so vô nghĩa, và nó vô nghĩa trong IM LẶNG."
+      },
+      {
+        "field": "implemented_by",
+        "actors": [
+          "generate-code",
+          "generate-bdd"
+        ],
+        "why": "Phân biệt UNTRACKED (chưa có code) với ORPHANED (code còn, spec mất). Đọc sai thì `/generate-bdd` xoá row của một scenario ĐÃ có code ⇒ method đó thành vô hình: không cờ nào, không report nào, mà vẫn được caller gọi."
+      },
+      {
+        "field": "test_count",
+        "actors": [
+          "validate-traces"
+        ],
+        "why": "Quyết GAP vs OK. Không đọc thì mọi row có code đều thành OK ⇒ coverage báo xanh trên scenario chưa có một test nào."
+      }
+    ]
+  },
+  "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": "`integration`",
+      "reason": "Giá trị cột `fe_phase` là `integrated` (CÓ hậu tố -ed). Dạng không -ed chỉ thuộc về CỜ `--phase=integration`. Ghi sai vào sổ thì `--lint-trace` T3 báo lỗi enum, VÀ `fe_integrated` ở /validate-traces Step 7 đếm `integrated` nên counter mãi bằng 0 trong im lặng — đúng hình dạng G1 (cờ im lặng). R6 ĐÃ DỰ ĐOÁN ca này (comment của nó: 'G19 là ca này') và chỉ đúng công cụ là forbidden_patterns — nhưng chưa ai khai. Nó tái diễn thật ở 0.9.0: bốn chỗ trong hai lệnh ghi giá trị cột là dạng không -ed, và CHÍNH validate-traces.tmpl tự mâu thuẫn: một dòng bảo ghi dạng đó, dòng khác đếm `integrated`.",
+      "gap": "G19/G61"
+    },
+    {
+      "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"
+    }
+  ]
+}