@educa-corp/sdd-framework 0.5.0 → 0.6.0

package/bin/trace-schema.json

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