@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/bin/trace-schema.json

@@ -937,17 +937,37 @@
         "Đội/submodule sở hữu scenario. Nguồn: @trace.service của header .feature.",
         "VÌ SAO TỒN TẠI (G31): validate-traces Step 0 và trace-mirror.md đều khẳng định trace gộp",
         "'không cần tách theo service vì mỗi row mang @trace.service' — nhưng TSV KHÔNG có cột nào",
-        "cho nó và JSON report cũng không. Ở đúng chế độ phổ biến nhất (umbrella + spec_source),",
-        "trace hoàn toàn không trả lời được 'scenario này thuộc đội nào' — câu hỏi số MỘT của một",
-        "dự án nhiều đội. Nghịch lý: nhánh LEGACY (trace tách theo service) thì CÓ gắn field service",
-        "vào JSON; nhánh 'phổ biến' thì không. Cột này làm lời khẳng định kia thành sự thật.",
-        "Giá trị: path service | 'multi' (chưa chốt) | 'unresolved' (routing sai) | '—' (single-service)."
+        "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"
+        "generate-bdd",
+        "validate-traces"
       ],
       "read_by": [
-        "validate-traces"
+        "validate-traces",
+        "generate-code"
       ]
     },
     {
@@ -1063,6 +1083,19 @@
   ],
   "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",
@@ -1078,13 +1111,19 @@
         "web",
         "app",
         "system"
-      ]
+      ],
+      "filename_segment": "{UC-ID}-{platform}.tsv",
+      "$filename_note": "Tên sổ là nơi DUY NHẤT mang platform của row — validate-traces Step 2 lấy platform từ đây để tìm .feature đúng thư mục con. Sổ thiếu đoạn này thì cả sổ vô hình (đúng hình dạng G3/G8)."
     },
     "approval_status": {
       "values": [
         "draft",
         "in-review",
         "approved"
+      ],
+      "columns": [
+        "prd_status",
+        "uc_status"
       ]
     },
     "fe_phase": {
@@ -1094,15 +1133,48 @@
       ],
       "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",
@@ -1116,10 +1188,549 @@
         "SEAM_UNWIRED",
         "STUB_UNRESOLVED",
         "SEAM_PENDING",
-        "STUB_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": "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_template": "templates/ci/trace-gate.yml",
+      "tags": [
+        {
+          "tag": "@trace.implements",
+          "flags": [
+            "ORPHANED",
+            "TRACE_ORPHAN"
+          ]
+        },
+        {
+          "tag": "@trace.verifies",
+          "flags": [
+            "ORPHANED",
+            "TRACE_ORPHAN"
+          ]
+        },
+        {
+          "tag": "@trace.seam_port",
+          "flags": [
+            "SEAM_UNWIRED"
+          ]
+        },
+        {
+          "tag": "@trace.seam_pending",
+          "flags": [
+            "SEAM_UNWIRED"
+          ]
+        },
+        {
+          "tag": "@trace.stub",
+          "flags": [
+            "STUB_UNRESOLVED"
+          ]
+        },
+        {
+          "tag": "@trace.stub_owner",
+          "flags": [
+            "STUB_UNRESOLVED"
+          ]
+        },
+        {
+          "tag": "@trace.stub_for",
+          "flags": [
+            "STUB_UNRESOLVED"
+          ]
+        }
+      ]
+    },
+    "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 chỉ có một",
+      "cổng chặn-cứng rồi vẫn ghi đè (mất changelog, đánh số lại BR) · /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"
+      }
+    ]
+  },
   "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",