@educa-corp/sdd-framework 0.6.0 → 0.7.1

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"
       ]
     },
     {
@@ -1087,10 +1107,36 @@
       "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"
+        "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)."
@@ -1154,6 +1200,7 @@
     "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",
@@ -1167,7 +1214,8 @@
         "SEAM_UNWIRED",
         "STUB_UNRESOLVED",
         "SEAM_PENDING",
-        "STUB_PENDING"
+        "STUB_PENDING",
+        "SERVICE_UNROUTED"
       ]
     }
   },
@@ -1245,17 +1293,48 @@
       ],
       "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" }
+        {
+          "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/)" }
+        {
+          "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": {
@@ -1292,38 +1371,150 @@
       ],
       "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"] }
+        {
+          "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"],
+        "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"],
+        "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"],
+        "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"],
+        "label_fields": [
+          "artifact",
+          "consumer_uc"
+        ],
         "why": "hàm rỗng chưa được lấp, nhưng caller đã gọi"
       }
     ],
@@ -1339,7 +1530,9 @@
         "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" },
+      "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",
@@ -1363,13 +1556,207 @@
           "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"],
+        "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"
+      }
+    ]
+  },
   "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",

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.6.0
+0.7.1