@educa-corp/sdd-framework 0.9.6 → 0.9.7

package/bin/trace-schema.json

@@ -28,7 +28,9 @@
     "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",
+    "qc-design-script": "commands/qc-design-script.tmpl",
+    "qc-run-script": "commands/qc-run-script.tmpl",
+    "qc-run-manualtest": "commands/qc-run-manualtest.tmpl",
     "report-bug": "commands/report-bug.tmpl",
     "propose-scenario": "commands/propose-scenario.tmpl",
     "fix-bug": "commands/fix-bug.tmpl",
@@ -194,14 +196,14 @@
       "shape": "{UC-ID}-SC{N}",
       "written_by": [
         "dev-gen-test",
-        "qc-run-test",
+        "qc-design-script",
         "fix-bug"
       ],
       "read_by": [
         "validate-traces",
         "review-code",
         "dev-run-test",
-        "qc-run-test"
+        "qc-run-script"
       ],
       "why": "Khớp test → sc_id khi ghi test_count/dev_selftest/qc_status."
     },
@@ -477,11 +479,11 @@
       ],
       "read_by": [
         "generate-code",
-        "qc-run-test",
+        "qc-design-script",
         "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."
+      "$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-design-script đọ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-design-script). 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",
@@ -663,7 +665,8 @@
         "generate-code",
         "dev-gen-test",
         "dev-run-test",
-        "qc-run-test",
+        "qc-run-script",
+        "qc-run-manualtest",
         "report-bug",
         "fix-bug"
       ]
@@ -761,7 +764,8 @@
       ],
       "read_by": [
         "validate-traces",
-        "qc-run-test"
+        "qc-run-script",
+        "qc-run-manualtest"
       ]
     },
     {
@@ -776,15 +780,17 @@
       ],
       "read_by": [
         "validate-traces",
-        "qc-run-test"
+        "qc-run-script",
+        "qc-run-manualtest"
       ]
     },
     {
       "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.",
+      "$comment": "Chủ (ghi pass/fail/skip): qc-run-script + qc-run-manualtest — HAI chủ kể từ Đợt 2 · b2, và KHÔNG có chủ thứ ba. 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",
+        "qc-run-script",
+        "qc-run-manualtest",
         "generate-bdd",
         "generate-code",
         "map-testids"
@@ -800,9 +806,10 @@
     {
       "n": 11,
       "name": "qc_run_at",
-      "$comment": "Chủ: qc-run-test. Invalidator (hạ về —): generate-bdd · generate-code · map-testids. Xem qc_status.",
+      "$comment": "Chủ: qc-run-script + qc-run-manualtest. Invalidator (hạ về —): generate-bdd · generate-code · map-testids. Xem qc_status.",
       "written_by": [
-        "qc-run-test",
+        "qc-run-script",
+        "qc-run-manualtest",
         "generate-bdd",
         "generate-code",
         "map-testids"
@@ -817,7 +824,8 @@
       "n": 12,
       "name": "qc_owner",
       "written_by": [
-        "qc-run-test",
+        "qc-run-script",
+        "qc-run-manualtest",
         "report-bug"
       ],
       "read_by": [
@@ -830,13 +838,15 @@
       "n": 13,
       "name": "qc_blocked_by",
       "written_by": [
-        "qc-run-test",
+        "qc-run-script",
+        "qc-run-manualtest",
         "report-bug"
       ],
       "read_by": [
         "validate-traces",
         "generate-code",
-        "qc-run-test"
+        "qc-run-script",
+        "qc-run-manualtest"
       ]
     },
     {
@@ -950,7 +960,8 @@
         "validate-traces",
         "generate-code",
         "dev-run-test",
-        "qc-run-test"
+        "qc-run-script",
+        "qc-run-manualtest"
       ]
     },
     {
@@ -1021,7 +1032,8 @@
         "generate-code",
         "dev-gen-test",
         "dev-run-test",
-        "qc-run-test",
+        "qc-run-script",
+        "qc-run-manualtest",
         "review-context",
         "review-tech-docs",
         "fix-bug"
@@ -1077,7 +1089,7 @@
       ],
       "read_by": [
         "fix-bug",
-        "qc-run-test"
+        "qc-run-script"
       ]
     },
     {
@@ -1332,33 +1344,97 @@
         "sinh ra bản đang có?"
       ],
       "label_marker": "Checkpoint:",
+      "unconditional_hard_budget": {
+        "max": 3,
+        "current": [
+          "extend-prd",
+          "amend-prd",
+          "refine-prd"
+        ],
+        "why": [
+          "SỐ CỔNG CỨNG NỔ Ở MỌI LẦN CHẠY — không phải tổng số lệnh `hard`.",
+          "",
+          "Đo 2026-09-16: 12 lệnh ở `hard`, nhưng 9 trong đó khai `narrowing` nên chỉ nổ khi ĐÃ",
+          "có thứ để mất (file đã tồn tại / bảng đã có row / findings đã có quyết định). Chạy một",
+          "lượt đầu trọn vẹn: 0 cổng cứng nổ. Con số gây lo lắng là 12; con số ĐÚNG là 3.",
+          "",
+          "VÌ SAO PHẢI CÓ HẠN MỨC: `--yes` KHÔNG bỏ qua được `hard`. Nên khi `hard` trở nên phiền,",
+          "người dùng không thêm `--yes` — họ GỠ LỆNH KHỎI `hard`, và mất luôn những cổng đáng",
+          "giữ. Một cơ chế cổng chặn quá dày không làm hệ thống an toàn hơn rồi chậm hơn; nó làm",
+          "hệ thống KÉM an toàn hơn, vì nó tiêu huỷ chính cơ chế nó thuộc về. gate.md Bước 3b tồn",
+          "tại vì đúng rủi ro đó: Y thành phản xạ và cổng hỏng âm thầm.",
+          "",
+          "BA LỆNH HIỆN TẠI đều là sửa một PRD ĐÃ DUYỆT — không tồn tại lần chạy vô hại, nên cổng",
+          "nổ mọi lần là ĐÚNG BẢN CHẤT.",
+          "",
+          "TĂNG SỐ NÀY LÀ MỘT QUYẾT ĐỊNH, KHÔNG PHẢI MỘT HỆ QUẢ. R20 chặn build khi vượt, nên việc",
+          "vượt phải là một lần sửa contract NHÌN THẤY TRONG DIFF. Nếu đang định nâng vì N3: kiểm",
+          "xem lệnh đó có THẬT SỰ không có lần chạy vô hại không, hay chỉ là chưa ai ngồi nghĩ ra",
+          "điều kiện cho nó."
+        ]
+      },
       "hard": [
+        {
+          "cmd": "qc-automation-assess",
+          "narrowing": "chỉ nổ khi `AUTOMATION_ASSESSMENT.md` ĐÃ TỒN TẠI. Lần đánh giá đầu không ghi đè gì, đi thẳng.",
+          "why": "ghi đè bảng đánh giá đã có → mất quyết định `Automatable: Y/N` + nhãn lý do đã chốt, và XOÁ cột `Script file` do /qc-design-script điền — chỉ mục ngược duy nhất từ TC sang file code",
+          "$narrowing_note": "Khác /qc-review-testcase (cũng ghi một file QC nhưng ở mức `none`): biên bản soát là KẾT QUẢ CỦA MỘT LƯỢT ĐỌC, soát lại là đúng bản chất. Bảng này là QUYẾT ĐỊNH TÍCH LUỸ, và một nửa của nó do LỆNH KHÁC điền."
+        },
+        {
+          "cmd": "generate-bdd",
+          "narrowing": "chỉ nổ khi Version Check chọn `F` (gen lại TOÀN BỘ scenario) — nhánh DUY NHẤT đánh số lại `sc_id`. Chọn `Y` (cập nhật hẹp) không mất gì và đi thẳng; lần gen đầu cũng đi thẳng. Xem §Chạy lại.",
+          "why": "ghi đè `.feature` đã có — mode F gen lại TOÀN BỘ scenario, ĐÁNH SỐ LẠI `sc_id` mà sổ TSV, tag `@trace.verifies` trong code và `.Test.md` đều đang trỏ vào"
+        },
+        {
+          "cmd": "generate-tech-docs",
+          "narrowing": "chỉ nổ khi trả lời `Y` (merge/mở rộng) cho một UC ĐÃ CÓ nội dung trong doc. UC mới và `N` (bỏ qua UC) đi thẳng; doc chưa tồn tại cũng đi thẳng. Xem §Chạy lại.",
+          "why": "ghi đè/mở rộng tech-doc gộp đã có — doc chứa §4.5.6 Test Selectors do SA VIẾT TAY và §12 GAP Register, cả hai không suy lại được từ BDD"
+        },
+        {
+          "cmd": "generate-code",
+          "narrowing": "chỉ nổ khi trạng thái của UC là `drifted` hoặc `synced` (Bước 1 phân biệt qua sổ TSV). Trạng thái `new` — chưa có code — đi thẳng, gồm cả ca headless `claude -p \"/generate-code UC1 --yes\"` mà gate.md nêu làm ví dụ. Xem §Chạy lại.",
+          "why": "ghi đè mã nguồn đã có — dev SỬA TAY chính các file này; trước 2026-09-16 lệnh đứng ở mức `normal`, tức `--yes` ghi đè bản sửa tay TRONG IM LẶNG"
+        },
+        {
+          "cmd": "define-product",
+          "narrowing": "chỉ nổ khi file product-definition ĐÃ TỒN TẠI và có ≥1 mục mang `✅ PO xác nhận`. Buổi discovery đầu đi thẳng, và resume khi chưa mục nào được chốt cũng đi thẳng. Xem §Chạy lại.",
+          "why": "ghi đè product-definition đã có — từng mục mang dấu `✅ PO xác nhận`, và `Completed Phase` cho phép resume; ghi đè là xoá cả vòng xác nhận của PO"
+        },
         {
           "cmd": "generate-prd",
+          "narrowing": "chỉ chạm tới khi PRD ĐÃ TỒN TẠI — và khi đó lệnh DỪNG HẲN, không cả hỏi Y/N (Bước 1: \"Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi Y/N\"). PRD chưa có: đi thẳng.",
           "why": "ghi đè PRD đã có → mất changelog, ĐÁNH SỐ LẠI BR, phá @trace.business_rules trong mọi .feature đã sinh"
         },
         {
           "cmd": "extend-prd",
+          "narrowing": null,
+          "narrowing_why": "KHÔNG có lần chạy vô hại — lệnh chỉ chạy được trên PRD ĐÃ DUYỆT (chưa có PRD thì dùng /generate-prd). Cổng nổ mọi lần là đúng bản chất, không phải chỗ sót.",
           "why": "sửa PRD đã DUYỆT"
         },
         {
           "cmd": "amend-prd",
+          "narrowing": null,
+          "narrowing_why": "KHÔNG có lần chạy vô hại — đây là 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ũ. Mọi lần chạy đều làm mất nội dung đã duyệt, CÓ CHỦ Ý.",
           "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",
+          "narrowing": null,
+          "narrowing_why": "KHÔNG có lần chạy vô hại ở nhánh `--resume`: nó áp findings thẳng vào PRD đã duyệt rồi bump version. (Nhánh phân tích tự DỪNG khi PRD chưa đổi từ lần review trước — đó là guard của lệnh, không phải điều kiện của cổng.)",
           "why": "--resume áp findings trực tiếp vào PRD"
         },
         {
           "cmd": "generate-architecture",
+          "narrowing": "chỉ nổ khi architecture.md đã có VÀ `verified_by` là `AI-draft`/trống. `verified_by: {người thật}` → KHÔNG đè, nhảy Bước 6 refresh có kiểm soát. File chưa có: đi thẳng.",
           "why": "ghi đè architecture.md đã verified_by một người thật"
         },
         {
           "cmd": "dev-gen-test",
+          "narrowing": "chỉ nổ khi file test ĐÃ TỒN TẠI. Lần sinh đầu đi thẳng.",
           "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)",
+            "                          /qc-design-script (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",
@@ -1382,6 +1458,7 @@
         },
         {
           "cmd": "map-testids",
+          "narrowing": "chỉ nổ khi §4.5.6 ĐÃ CÓ ROW. Tech-doc chưa có bảng — brownfield thật, ca lệnh này sinh ra để phục vụ — đi thẳng.",
           "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.",
@@ -1395,7 +1472,8 @@
           ]
         },
         {
-          "cmd": "qc-run-test",
+          "cmd": "qc-design-script",
+          "narrowing": "chỉ nổ khi SINH LẠI file script đã tồn tại. Chạy lại test trên script không đổi: đi thẳng.",
           "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.",
@@ -1417,9 +1495,10 @@
         },
         {
           "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",
+          "narrowing": "chỉ nổ khi file `.Test.md` ĐÃ TỒN TẠI. Lần thiết kế đầu không ghi đè gì, đi thẳng.",
+          "why": "ghi đè *.Test.md đã qua cổng HITL /qc-review-testcase → 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.",
+            "G78 — cùng khuôn G67/G77 nhưng 🟠, vì /qc-review-testcase 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.",
             "",
@@ -1433,6 +1512,7 @@
         },
         {
           "cmd": "qc-analyze",
+          "narrowing": "chỉ nổ khi `DOC_GAP.md` ĐÃ TỒN TẠI. Lần chạy đầu không ghi đè gì, đi thẳng.",
           "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:",
@@ -1456,28 +1536,30 @@
             "",
             "Đườ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á."
           ]
+        },
+        {
+          "cmd": "review-context",
+          "why": "ghi đè quyết định reviewer — `--full` BỎ QUA findings cũ (mất status accepted/modified/rejected của cả một vòng Review Board), và `--resume` áp fix THẲNG vào PRD/.feature rồi bump version. Cùng hình dạng /refine-prd, lệnh đó đã `hard` từ trước. CHUYỂN TỪ `none` 2026-09-16 (N2)",
+          "narrowing": "Mức cứng chỉ áp khi file findings ĐÃ TỒN TẠI và có ≥1 finding mang status accepted/modified/rejected (đã qua Review Board), HOẶC khi chạy với --full/--resume. Lần phân tích đầu không ghi đè gì — bắt CHECKPOINT cứng ở đó là ồn vô cớ. Cùng khuôn map-testids."
+        },
+        {
+          "cmd": "review-tech-docs",
+          "why": "ghi đè quyết định reviewer (`--full`), và `--resume` Phase 2–3 ghi vào THÂN tech-doc, HEADER (@trace.bdd_versions · @trace.sign_off — sign_off là xác nhận của NGƯỜI), và sổ TSV của MỌI UC mà doc phủ. CHUYỂN TỪ `none` 2026-09-16 (N2)",
+          "narrowing": "Như /review-context — chỉ áp khi findings đã có quyết định reviewer, hoặc khi chạy --full/--resume."
         }
       ],
       "none": [
         {
           "cmd": "review-code",
-          "why": "read-only"
+          "why": "ghi {lessons_path} qua steps/capture-lesson.md, nhưng CHỈ sau khi người trả lời Y cho câu hỏi tường minh (tmpl:140) — điều kiện đó ĐÃ là một cổng; thêm CHECKPOINT nữa là hỏi hai lần cho một hành động, và hỏi hai lần dạy người ta bấm Y theo phản xạ. KHÔNG phải read-only"
         },
         {
           "cmd": "validate-traces",
-          "why": "read-only (ghi trace-report.json + TSV status, không đụng spec/code)"
+          "why": "mọi thao tác ghi `when: always` đều hoặc dựng lại được (trace-report.json, .trace-mirror/) hoặc `append` (trace-history.jsonl — AUTHORITATIVE, KHÔNG regenerate được, nên nó an toàn CHỈ vì là append). Hai thao tác nguy hơn — row TSV và _seams.tsv — đều nằm sau `--reconcile-code`. KHÔNG phải read-only: tmpl:58 tự phân biệt chế độ đọc với `--reconcile-code (có GHI)`"
         },
         {
           "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/)"
+          "why": "như /review-code — ghi {lessons_path} sau câu hỏi (Y/N) ở tmpl:254. KHÔNG phải read-only"
         }
       ]
     },
@@ -2059,7 +2141,10 @@
       },
       {
         "column": "qc_status",
-        "owner": "qc-run-test",
+        "owner": [
+          "qc-run-script",
+          "qc-run-manualtest"
+        ],
         "positive_values": [
           "pass"
         ],
@@ -2079,7 +2164,7 @@
       "  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,",
+      "VÌ SAO CẦN CANH: trước khối này, bảng §4.5.6 được 3 lệnh ĐỌC (generate-code, qc-design-script,",
       "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).",
@@ -2106,7 +2191,7 @@
       {
         "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."
+        "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-design-script 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",
@@ -2146,7 +2231,8 @@
   },
   "artifact_writers": {
     "$comment": [
-      "AI GHI ARTIFACT NÀO, VÀ ARTIFACT ĐÓ CÓ PHẦN NGƯỜI NHẬP TAY KHÔNG (G74 · R18).",
+      "AI GHI ARTIFACT NÀO, KHI NÀO GHI, ARTIFACT ĐÓ CÓ PHẦN NGƯỜI NHẬP TAY KHÔNG, VÀ ĐÈ MẤT THÌ",
+      "DỰNG LẠI ĐƯỢC 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",
@@ -2155,116 +2241,552 @@
       "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.",
+      "R18 duyệt CHIỀU NGƯỢC LẠI: mọi lệnh trong `enrolled` phải khai đủ. Quên = BUILD ĐỎ, thay vì",
+      "quên = mở cửa. `why` BẮT BUỘC cả khi has_human_content:false — đó chính là G79.",
+      "",
+      "BA TRƯỜNG Ở CẤP ARTIFACT, KHÔNG Ở CẤP LỆNH — `mode` · `regenerable` · `when`:",
       "",
-      "`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.",
+      "  (D1 · mode + regenerable) `has_human_content` là cờ PHẲNG Ở CẤP LỆNH và không nói được:",
+      "  có loại file KHÔNG ai gõ tay vào nhưng VẪN không được đè vì nó DỒN THÊM qua từng lần chạy",
+      "  — `trace-history.jsonl`, mà chính /validate-traces gọi là AUTHORITATIVE, không regenerate",
+      "  được. Và một lệnh đụng NHIỀU artifact khác tính chất: /validate-traces GHI ĐÈ",
+      "  trace-report.json (dựng lại được) NHƯNG APPEND trace-history.jsonl (không dựng lại được).",
+      "  Một cờ phẳng cho cả lệnh thì BẮT BUỘC phải chọn một nửa để nói dối.",
       "",
-      "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à."
+      "  (D4 · when) Cùng lỗ hổng đó ở MỘT TẦNG CAO HƠN: hành vi ghi thuộc về CHẾ ĐỘ, không thuộc",
+      "  về lệnh. Đo 2026-09-15: NĂM lệnh tự khai 'read-only' và cả năm đều có ghi —",
+      "  /review-context, /review-tech-docs, /validate-traces, /review-code, /debug. Nhãn được đặt",
+      "  theo chế độ MẶC ĐỊNH, rồi chế độ --resume/--reconcile-code thêm vào sau mà không ai quay",
+      "  lại sửa nhãn. Chính validate-traces.tmpl:58 đã viết sẵn phân biệt đó: 'Với một lệnh CHỈ ĐỌC",
+      "  thì đó là đốt thời gian. Với --reconcile-code (CÓ GHI) thì...'. Lệnh biết; registry trước",
+      "  đây không có ô để chứa.",
+      "",
+      "PHẠM VI — ĐỦ 33/33 LỆNH kể từ N3 (2026-09-16): `enrolled` 32 · `non_writers` 1",
+      "(`dev-smoke-test` — rà rồi, không ghi gì) · `pending_enrollment` RỖNG.",
+      "",
+      "Đi qua bốn đợt: 8 (GAPS-v5) → +5 (N1: đã ở `hard` sẵn, khai thêm không đổi hành vi lệnh",
+      "nào) → +5 (N2: nhóm tự khai 'read-only' mà cả năm đều CÓ ghi) → +14 (N3: phần còn lại).",
+      "",
+      "GIỮ `pending_enrollment` DÙ NÓ RỖNG: lệnh thêm về sau mà chưa rà phải có chỗ để KHAI RA,",
+      "thay vì rơi vào mặc định `normal` trong im lặng. 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à."
     ],
+    "write_modes": {
+      "$comment": [
+        "TỪ VỰNG `mode` — ba giá trị, phân biệt theo DUY NHẤT một câu hỏi: thao tác này có làm MẤT",
+        "nội dung đang có không?",
+        "",
+        "CHỈ `append` LÀ AN TOÀN VÔ ĐIỀU KIỆN. `merge` KHÔNG an toàn: /amend-prd là merge, và nó tự",
+        "khai là '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ũ'. Gộp merge chung với append là mở lại đúng cánh cửa vừa đóng.",
+        "",
+        "`create` THÊM Ở N3 (2026-09-16): /setup-ai-first ghi CLAUDE.md và project-context.yaml —",
+        "hai artifact người sửa tay nhiều nhất — nhưng nó CHỈ TẠO KHI CHƯA CÓ ('skip nếu đã tồn",
+        "tại'). Không có `create` thì phải khai `overwrite` (nói dối) hoặc `append` (cũng sai).",
+        "RỦI RO NẰM Ở THAO TÁC, KHÔNG Ở ARTIFACT — đây là ca chứng minh điều đó."
+      ],
+      "overwrite": "Viết đè toàn bộ file. Mọi nội dung cũ mất.",
+      "merge": "Sửa/thêm một phần, phần còn lại giữ nguyên. VẪN có thể mất phần bị đụng.",
+      "append": "Chỉ thêm bản ghi mới, KHÔNG sửa và KHÔNG xoá bản ghi cũ. Không mất gì.",
+      "create": "CHỈ tạo khi chưa có; file đã tồn tại thì BỎ QUA hoàn toàn. Không mất gì.",
+      "$creates_flag": "Cờ `creates: true` đặt Ở TỪNG ARTIFACT, đi KÈM `mode` chứ không thay nó (R22). Nó nói: thao tác này là `merge` khi file đã có, VÀ sinh ra file khi chưa có. Cần vì `merge` một mình không hứa file tồn tại — nếu MỌI lệnh ghi một artifact đều chỉ merge thì không ai tạo nó, và cả chuỗi trạm sau đứng chờ một file không bao giờ xuất hiện. Ép chúng khai `overwrite` thay vì dùng cờ này là NÓI DỐI: chế độ delta của file findings GIỮ `status` của reviewer."
+    },
+    "safe_modes": {
+      "$comment": [
+        "MODE NÀO ĐƯỢC MIỄN LUẬT (B) — tức mode nào KHÔNG THỂ làm mất nội dung đang có.",
+        "",
+        "Khai ở đây thay vì hard-code trong checker: thêm một mode mới mà quên dạy checker là",
+        "đúng kiểu lỗi R18 sinh ra để bắt. Và để danh sách này NGẮN là có chủ ý — `merge` KHÔNG",
+        "nằm trong đây, vì /amend-prd là merge và nó tự khai là thao tác ghi DUY NHẤT được phép",
+        "làm output KHÔNG phải superset của bản cũ."
+      ],
+      "modes": [
+        "append",
+        "create"
+      ]
+    },
+    "write_conditions": {
+      "$comment": [
+        "TỪ VỰNG `when` — thao tác ghi này xảy ra Ở CHẾ ĐỘ NÀO (D4 · 2026-09-15).",
+        "",
+        "LUẬT (B) CỦA R18 CHỈ ÉP `hard` KHI `when: always`. Ghi có điều kiện thì người dùng đã phải",
+        "gõ THÊM một cờ, hoặc đã phải trả lời Y cho một câu hỏi — bản thân việc đó đã là một cổng.",
+        "Ép `hard` cho cả lệnh vì một nhánh hiếm là phạt nhầm chế độ đọc: /validate-traces chạy hàng",
+        "ngày ở chế độ đọc, và dựng cổng chặn lên nó vì nhánh --reconcile-code sẽ dạy người ta thêm",
+        "`--yes` vào script — rồi `--yes` đó nằm lại vĩnh viễn, kể cả cho ngày họ chạy --reconcile-code.",
+        "",
+        "ĐỔI LẠI, R18 ĐÒI LỜI KHAI PHẢI KIỂM CHỨNG ĐƯỢC: `when` là tên cờ thì tmpl PHẢI nhắc đúng cờ",
+        "đó; `when: confirm` thì tmpl PHẢI có câu hỏi (Y/N). Khai một điều kiện không tồn tại thì luật",
+        "trông như đã được áp trong khi không ai áp — đúng bài học R17."
+      ],
+      "always": "Ghi ở MỌI lần chạy, không cần cờ và không hỏi thêm.",
+      "confirm": "Chỉ ghi sau khi người trả lời Y cho một câu hỏi tường minh (Y/N) trong lệnh.",
+      "--<flag>": "Chỉ ghi khi người dùng gõ thêm đúng cờ đó. Giá trị khai phải là tên cờ thật, có mặt trong tmpl."
+    },
     "enrolled": {
-      "qc-analyze": {
+      "generate-prd": {
         "writes": [
-          "DOC_GAP.md",
-          "REQUIREMENT_ANALYSIS.md",
-          "{refinement_dir}/{TICKET-ID}-qa-findings.yaml"
+          { "path": "{specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md",
+            "mode": "overwrite", "regenerable": false, "when": "always",
+            "note": "Mất toàn bộ `# Change Log` (và file changelog/ đã rollover), ĐÁNH SỐ LẠI BR, phá `@trace.business_rules` trong mọi .feature đã sinh. Cả ba không hoàn tác được từ trong lệnh, và cái thứ ba lan RA NGOÀI file." }
         ],
         "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."
+        "why": "PRD là tài liệu PO viết và KÝ DUYỆT. Lệnh DỪNG HẲN chứ không hỏi Y/N khi PRD đã có — tmpl:167 nói rõ vì sao: 'ghi đè một PRD đã ký duyệt không phải thứ nên nằm sau một phím bấm'."
       },
-      "qc-run-test": {
+      "extend-prd": {
         "writes": [
-          "test Python pytest-playwright",
-          "Page Object"
+          { "path": "{specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md",
+            "mode": "merge", "regenerable": false, "when": "always",
+            "note": "ADD-ONLY: Bước 5 §3 đòi output là SUPERSET CHẶT — mọi UC/AC/BR/row bảng/dòng changelog/cross-ref cũ còn nguyên si, và có guard sau-ghi tự chặn clobber. Nhưng nội dung PRD do người viết và duyệt, nên phần bị đụng mất là mất hẳn." },
+          { "path": "{specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md",
+            "mode": "append", "regenerable": false, "when": "always",
+            "note": "Kho changelog. Rollover đẩy row vượt 5 từ PRD sang ĐẦU bảng file này, không sửa và không xoá row cũ. Dựng lại KHÔNG được: PRD chỉ còn giữ 5 row gần nhất, phần cũ chỉ tồn tại ở đây." }
         ],
         "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."
+        "why": "Sửa PRD đã DUYỆT. Dù là add-only, phần bị đụng (`Status` → draft, bảng Change Log, §1c Phụ thuộc liên service) nằm trong tài liệu PO sở hữu. Dòng changelog còn là CONTRACT: /generate-bdd đọc nó để quyết cập nhật hẹp hay gen lại, /validate-traces đọc nó để lọc PRD_DRIFT vs PRD_STALE_REF."
+      },
+      "amend-prd": {
+        "writes": [
+          { "path": "{specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md",
+            "mode": "merge", "regenerable": false, "when": "always",
+            "note": "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ũ (tmpl:30). Sửa TẠI CHỖ một AC/BR/UC đã duyệt — nội dung cũ mất CÓ CHỦ Ý, và guard chỉ giới hạn PHẠM VI mất trong `amend_targets`, không ngăn việc mất." },
+          { "path": "{specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md",
+            "mode": "append", "regenerable": false, "when": "always",
+            "note": "Như /extend-prd — rollover, không đụng row cũ." }
+        ],
+        "has_human_content": true,
+        "why": "Đây là lệnh DUY NHẤT được phép làm mất nội dung PRD đã duyệt. Chính vì thế nó phải chặn cứng: guard `amend_targets` canh chiều GIỚI HẠN (không sửa ngoài danh sách) chứ không canh được chiều BẢO TOÀN — cái mất trong phạm vi là cái PO cố ý yêu cầu mất, và chỉ PO xác nhận được."
+      },
+      "refine-prd": {
+        "writes": [
+          { "path": "{refinement_dir}/{prd-slug}-findings.yaml",
+            "mode": "merge", "creates": true, "regenerable": false, "when": "always",
+            "note": "CHỨA QUYẾT ĐỊNH CỦA NGƯỜI: `status` mỗi finding là accepted|modified|rejected|needs_discussion, và `modified` nghĩa là reviewer ĐÃ SỬA suggestion ngay trong Review Board. Sinh lại = xoá sạch một vòng review đã làm." },
+          { "path": "{specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md",
+            "mode": "merge", "regenerable": false, "when": "--resume",
+            "note": "Áp findings đã duyệt THẲNG vào PRD, bump version, ghi dòng changelog." },
+          { "path": "{specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md",
+            "mode": "append", "regenerable": false, "when": "--resume",
+            "note": "Rollover — Phase 3 của lệnh này chính là bản gốc mà /extend-prd và /amend-prd tái dùng." }
+        ],
+        "has_human_content": true,
+        "why": "HAI lớp người, không phải một: reviewer quyết accepted/modified/rejected ngay trong file findings (ghi ở MỌI lần chạy), và PRD là tài liệu PO duyệt (chỉ ghi khi --resume). Cờ `has_human_content` ở cấp lệnh không phân biệt được hai lớp đó."
+      },
+      "generate-architecture": {
+        "writes": [
+          { "path": "{specs_dir}/architecture.md  ·  umbrella: {service}/specs/architecture.md",
+            "mode": "overwrite", "regenerable": false, "when": "always",
+            "note": "CHỈ đè khi `verified_by: AI-draft` hoặc trống. `verified_by: {người thật}` → KHÔNG đè, nhảy Bước 6 refresh có kiểm soát: chỉ ĐỀ XUẤT diff để SA tự áp, và KHÔNG tự đổi `verified_by`." }
+        ],
+        "has_human_content": true,
+        "why": "File mang chữ ký một người thật ở `verified_by`, và chữ ký đó có hiệu lực RA NGOÀI file: /generate-tech-docs Bước 0.5 [ARCH] dùng nó để quyết doc là RÀNG BUỘC KIẾN TRÚC CHÍNH THỨC hay chỉ là AI-draft bị gắn ⚠️ và xuống hạng sau CLAUDE.md/BDD. Đè lên một file đã verified là xoá chữ ký của người khác."
+      },
+      "qc-analyze": {
+        "writes": [
+          { "path": "{qc_artifact_dir}DOC_GAP.md",
+            "mode": "overwrite", "regenerable": false, "when": "always",
+            "note": "PO điền TAY cột `Trạng thái` (Open/Answered) và cột `Câu trả lời`. Ghi đè còn ĐÁNH SỐ LẠI mã GAP-UC{N}-{nnn} mà mọi .Test.md đang tham chiếu qua dấu 🚫 Block." },
+          { "path": "{qc_artifact_dir}REQUIREMENT_ANALYSIS.md",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Bản phân tích hợp nhất, suy hoàn toàn từ PRD + §12 tech-doc. Không ô nào cho người điền." },
+          { "path": "{refinement_dir}/{TICKET-ID}-qa-findings.yaml",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "CÙNG dữ liệu gap của DOC_GAP.md, đổi sang định dạng Review Board đọc được — dựng lại từ DOC_GAP." }
+        ],
+        "has_human_content": true,
+        "why": "PO điền TAY vào DOC_GAP.md — không sinh lại được. Hai artifact còn lại thì sinh lại được; chính sự khác nhau đó là lý do `regenerable` phải nằm ở cấp artifact chứ không ở cấp lệnh."
       },
       "qc-design-test": {
         "writes": [
-          "test-cases/*.Test.md"
+          { "path": "{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md",
+            "mode": "overwrite", "regenerable": false, "when": "always",
+            "note": "File đi qua cổng HITL /qc-review-testcase: `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. Ghi đè còn ĐÁNH SỐ LẠI TC_<FEATURE>_NNN mà REVIEW_<FEATURE>.md đang trỏ vào." }
+        ],
+        "has_human_content": true,
+        "why": "Chân thứ tư của hợp đồng test-id nằm ở file này (G64): giá trị id bị CHÉP CỨNG vào một artifact BỀN rồi nằm lại. Mất bản đã review là mất cả vòng HITL lẫn điểm neo của hợp đồng."
+      },
+      "qc-automation-assess": {
+        "writes": [
+          { "path": "{qc_artifact_dir}AUTOMATION_ASSESSMENT.md",
+            "mode": "merge", "creates": true, "regenerable": false, "when": "always", "human_content": true,
+            "note": "TẠO bảng ở lượt đầu, MERGE ở lượt sau (giữ quyết định Y/N + nhãn lý do của TC không DRIFT). Hai phần KHÔNG sinh lại được: (1) quyết định Y/N + nhãn lý do — người chốt sau khi cân nhắc ROI; (2) cột `Script file` do /qc-design-script điền, là CHỈ MỤC NGƯỢC DUY NHẤT từ TC → file code. Ghi đè là xoá công của hai bên cùng lúc." }
         ],
         "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."
+        "why": "Bảng này là NGUỒN DUY NHẤT cho ba trạm sau: /qc-design-script lọc `Automatable: Y`, /qc-run-script đọc cột `Script file` để biết chạy file nào, /qc-run-manualtest lọc `Automatable: N` để biết hỏi những TC nào. Mất nó thì cả ba đứt, và mắt xích /qc-run-script hỏng IM LẶNG nhất — suy sai đường dẫn là chạy 0 test mà vẫn báo xanh."
+      },
+      "qc-design-script": {
+        "writes": [
+          { "path": "tests/<project>/test_<feature>.py (module qc-playwright)",
+            "mode": "overwrite", "regenerable": false, "when": "always", "human_content": true,
+            "note": "QC SỬA TAY chính các file này — /qc-run-script §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." },
+          { "path": "pages/<feature>_page.py — Page Object",
+            "mode": "overwrite", "regenerable": false, "when": "always", "human_content": true,
+            "note": "Cùng lý do — QC sửa tay locator ở đây khi §4.5.6 đổi." },
+          { "path": "{qc_artifact_dir}AUTOMATION_ASSESSMENT.md — cột `Script file`",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Chỉ điền đường dẫn script cho từng TC; suy lại được từ cây file script." },
+          { "path": "{qc_artifact_dir}TESTABILITY_IMPROVEMENTS.md",
+            "mode": "append", "regenerable": false, "when": "always",
+            "note": "Mỗi rào cản kỹ thuật một mục IMPROVE-{date}-{NN}. CHỈ THÊM, không sửa mục cũ — nó là sổ đề xuất gửi FE/BE, và trạng thái 🟡 Proposed do người đổi." }
+        ],
+        "has_human_content": true,
+        "why": "KẾ THỪA vai ghi script của /qc-run-test (G77): lệnh bảo QC sửa tay, rồi lần sinh sau tự xoá bản sửa đó. Sau Đợt 2 · b2 lệnh này KHÔNG còn chạy test và KHÔNG ghi sổ trace — hai việc đó về /qc-run-script và /qc-run-manualtest."
+      },
+      "qc-run-script": {
+        "writes": [
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv — cột qc_status · qc_run_at · qc_owner · qc_blocked_by · last_updated",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Chỉ đụng cột nó SỞ HỮU, giữ nguyên cột của /dev-gen-test và /dev-run-test. Chạy lại test là có lại." },
+          { "path": "{bug_reports_dir}/{BUG-ID}.md — chuyển 🟡 Fixed → 🟢 Closed",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Chỉ LẬT field State và THÊM một dòng Verified — cả hai suy ra từ kết quả lần chạy, nên dựng lại được bằng cách chạy lại, và đóng nhầm thì mở lại được. Nội dung bug do /report-bug viết, lệnh này không đụng. Lệnh là CHỦ SỞ HỮU bước đóng bug. Đóng sai thì defect biến mất khỏi tầm nhìn — nên nó có guard riêng: bug đang 🟢 Open mà test pass thì KHÔNG đóng, chỉ ghi chú cảnh báo." },
+          { "path": "./.trace-mirror/ (panel mirror, qua steps/trace-mirror.md)",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh lại được bất cứ lúc nào, luôn gitignore." }
+        ],
+        "has_human_content": false,
+        "why": "KHÔNG sinh và KHÔNG sửa file script — nó chỉ CHẠY. Mọi thứ nó ghi đều dựng lại được bằng cách chạy lại, trừ trạng thái bug (merge, có guard riêng). Vì thế mức `normal` là đúng, dù nó là một trong hai chủ của cột qc_status."
+      },
+      "qc-run-manualtest": {
+        "writes": [
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv — cột qc_status · qc_run_at · qc_owner · qc_blocked_by · last_updated",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "GHI NGAY sau mỗi câu trả lời, không gom cuối phiên — mất phiên giữa chừng không mất gì đã nhập, và chạy lại chỉ hỏi SC còn not_run (tự resume). Sổ trace là nguồn DUY NHẤT: không artifact trung gian nào để trôi." },
+          { "path": "{qc_artifact_dir}MANUAL_EVIDENCE.md",
+            "mode": "append", "regenerable": false, "when": "always", "human_content": true,
+            "note": "Một dòng mỗi lần ghi: ngày · sc_id · kết quả · NGƯỜI CHẠY · bằng chứng. CHỈ THÊM nên không trôi được. Đây là mức tương đương của 'output runner' ở /qc-run-script — `pass` không được phép là 'vì tôi nói vậy'." },
+          { "path": "./.trace-mirror/ (panel mirror, qua steps/trace-mirror.md)",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh lại được bất cứ lúc nào, luôn gitignore." }
+        ],
+        "has_human_content": true,
+        "why": "LỆNH THỨ BA, không có trong đề xuất gốc. Không có nó thì TC mang `Automatable: N` nằm not_run vĩnh viễn và /qc-report chấm cả PRD là FAIL — rồi đội QC sẽ hạ ngưỡng về 0 để verdict xanh, và cả Đợt 3 thành trang trí. Cách nhập CHỐT VỚI CHỊ QC 2026-09-16: hỏi từng TC, KHÔNG đọc file checklist — nguyên văn \"chị sợ đọc checklist mà lệch thông tin lại ghi kết quả sai\". Artifact có người nhập tay (MANUAL_EVIDENCE.md) là `append`, nên luật (A) không ép hard."
       },
       "qc-plan": {
         "writes": [
-          "TEST_PLAN.md"
+          { "path": "{qc_artifact_dir}TEST_PLAN.md",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "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." }
+        ],
+        "has_human_content": false,
+        "why": "Ghi đè AN TOÀN — và khai điều đó ra là có chủ đích. KHAI LẠI NẾU về sau có ai điền tay vào đây."
+      },
+      "qc-review-testcase": {
+        "writes": [
+          { "path": "{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Là BIÊN BẢN của một lượt soát test case. 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." }
         ],
         "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."
+        "why": "Ghi đè AN TOÀN. Kết luận của người soát KHÔNG nằm ở file này mà nằm ở *.Test.md (Status, Expected Result, 🚫 Block) — nên chính /qc-design-test mới là lệnh phải chặn cứng, không phải lệnh này. Lệnh cũng canh CHÂN THỨ TƯ của hợp đồng test-id (testid_fourth_leg.checked_by) và ĐỌC stamp trên *.Test.md (qc_artifact_stamp.checked_by) — cả hai vai đó chạy trên .Test.md nên chúng về vai TEST CASE khi /qc-review tách đôi (Đợt 2 · b1)."
       },
-      "qc-review": {
+      "qc-review-script": {
         "writes": [
-          "test-cases/REVIEW_<FEATURE>.md"
+          { "path": "{qc_artifact_dir}test-cases/REVIEW_SCRIPT_<FEATURE>.md",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Biên bản một lượt soát CODE TEST. File RIÊNG, không chung với REVIEW_<FEATURE>.md: hai lượt soát cách nhau vài trạm, chung file thì lượt sau đè bảng chi tiết của lượt trước, và trạm tiêu thụ verdict lại phải đoán nó thuộc vai nào — đúng vấn đề mà việc tách lệnh này giải quyết." }
         ],
         "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."
+        "why": "Ghi đè AN TOÀN, cùng lý do với /qc-review-testcase. Phần CÓ người sửa tay là code test mà lệnh này ĐỌC — và trạm sinh script đã ở mức hard vì đúng lý do đó (G77). An toàn ở phần nó GHI, không phải phần nó ĐỌC."
       },
       "qc-report": {
         "writes": [
-          "reports/<feature>/report.html",
-          "test-results/<nodeid>/trace.zip"
+          { "path": "reports/<feature>/report.html",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "pytest-html self-contained, sinh từ lần chạy /qc-run-script gần nhất." },
+          { "path": "test-results/<nodeid>/trace.zip",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Playwright Trace của cùng lần chạy đó." }
         ],
         "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."
+        "why": "Sinh hoàn toàn từ lần chạy gần nhất. Không có ô nào cho người điền, và không có trạng thái nào tích luỹ qua các lần chạy."
       },
       "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)"
+          { "path": "tech-doc gộp — §4.5.6 Test Selectors",
+            "mode": "merge", "regenerable": false, "when": "always",
+            "note": "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ó là {uc-lower}-{screen}-{element}-{type}. Mức cứng CHỈ áp khi §4.5.6 ĐÃ có row; bảng chưa có (brownfield thật) thì đi thẳng." },
+          { "path": "tech-doc header — @trace.testid_attr",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Một field scalar, suy từ stack FE." },
+          { "path": "figma-components catalog — Test-ID Forwarding",
+            "mode": "merge", "regenerable": true, "when": "--from-code",
+            "note": "Step 3. Chế độ mặc định BỎ QUA bước này — tmpl:20." },
+          { "path": "usage site FE",
+            "mode": "merge", "regenerable": true, "when": "--from-code",
+            "note": "Step 4. Chèn thuộc tính test-id vào đúng usage site, suy từ bảng §4.5.6 — không đụng logic quanh nó. Chế độ mặc định BỎ QUA." }
         ],
         "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."
+        "why": "Ghi đè §4.5.6 là ĐỔI hợp đồng mà cả FE lẫn QC đang bám vào, và kéo theo Step 5b hạ `qc_status` + bump `tech_doc_revision` cho một hợp đồng CHƯA HỎNG. Ba artifact còn lại đều sinh lại được — một mình §4.5.6 là lý do lệnh này phải chặn cứng."
       },
       "dev-gen-test": {
         "writes": [
-          "file unit/integration/E2E test theo module dev",
-          "sổ trace: test_count · test_classes · dev_selftest"
+          { "path": "file unit/integration/E2E test theo module dev",
+            "mode": "overwrite", "regenerable": false, "when": "always",
+            "note": "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'." },
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv — cột test_count · test_classes · dev_selftest",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Khớp row theo `sc_id`, GIỮ NGUYÊN mọi cột khác — `dev_selftest_at` do /dev-run-test sở hữu, `qc_status`/`qc_run_at` do /qc-run-script + /qc-run-manualtest sở hữu." },
+          { "path": "./.trace-mirror/ (panel mirror, qua steps/trace-mirror.md)",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh lại được bất cứ lúc nào, luôn gitignore. (Artifact này THIẾU trong bản khai N1 — phát hiện khi rà include ở N2.)" }
+        ],
+        "has_human_content": true,
+        "why": "Cùng khuôn G77 ở lane QC, khác lane: lệnh bảo người ta sửa tay, rồi lần chạy sau tự xoá bản sửa đó. Cột sổ trace và mirror thì ngược lại — máy tính ra, sinh lại được."
+      },
+      "review-code": {
+        "writes": [
+          { "path": "{lessons_path} — mặc định specs/domain-knowledge/lessons-learned.md, umbrella: {service_root}/.agent/project-lessons.md",
+            "mode": "merge", "regenerable": false, "when": "confirm",
+            "note": "Qua {{include:steps/capture-lesson.md}}. Lesson là GUARDRAIL do người chốt, tích luỹ qua nhiều phiên — không suy lại được từ code. capture-lesson L-35: nếu đã có lesson cùng lỗi thì SỬA lesson đó, nên là `merge` chứ không phải `append`." }
+        ],
+        "has_human_content": true,
+        "why": "GHI CÓ ĐIỀU KIỆN, và điều kiện ĐÃ LÀ một cổng: lệnh hỏi 'Ghi nó thành project lesson để /generate-code không lặp lại? (Y/N)' (tmpl:140). Thêm CHECKPOINT nữa là hỏi hai lần cho một hành động — cách nhanh nhất dạy người ta bấm Y theo phản xạ. Vì thế lệnh ở mức `none`, KHÔNG phải vì nó read-only. Dòng `Output Artifacts: none (read-only)` cũ là SAI — đã sửa 2026-09-16."
+      },
+      "debug": {
+        "writes": [
+          { "path": "{lessons_path} — mặc định specs/domain-knowledge/lessons-learned.md, umbrella: {service_root}/.agent/project-lessons.md",
+            "mode": "merge", "regenerable": false, "when": "confirm",
+            "note": "Qua {{include:steps/capture-lesson.md}}, cùng đường với /review-code và /fix-bug." }
+        ],
+        "has_human_content": true,
+        "why": "Như /review-code: ghi nằm sau câu hỏi 'Cái này trông như một lỗi AI lặp lại. Ghi nó thành project lesson? (Y/N)' (tmpl:254). capture-lesson §G46 còn cảnh báo file này 'phình nhanh nhất đúng lúc dự án đang trục trặc' — tức nó tích luỹ thật, không phải sổ tạm."
+      },
+      "review-context": {
+        "writes": [
+          { "path": "{refinement_dir}/{prd-slug}-review-context-findings.yaml  ·  BDD: {refinement_dir}/{uc-id}-{platform}-review-bdd-findings.yaml",
+            "mode": "merge", "creates": true, "regenerable": false, "when": "always",
+            "note": "CHỨA QUYẾT ĐỊNH CỦA NGƯỜI (status accepted|modified|rejected|needs_discussion, `applied_via`). Chế độ DELTA giữ finding cũ; nhưng `--full` BỎ QUA findings cũ (tmpl:64) ⇒ mất cả vòng Review Board. Tên file BẮT BUỘC có platform, thiếu là review platform này ĐÈ findings platform khác." },
+          { "path": "PRD hoặc .feature target (áp fix + bump version)",
+            "mode": "merge", "regenerable": false, "when": "--resume",
+            "note": "Resume Mode áp các finding được chấp nhận THẲNG vào target và bump version — `applied_to_version` ghi lại version vừa bump tới (tmpl:290)." }
+        ],
+        "has_human_content": true,
+        "why": "Tiêu đề tmpl khai 'READ-ONLY — ghi file findings, KHÔNG sửa target'. Đúng ở chế độ phân tích, SAI ở `--resume`. Và ngay chế độ phân tích cũng không vô hại: `--full` bỏ qua findings cũ, tức xoá quyết định reviewer. Cùng hình dạng với /refine-prd — lệnh đó đã ở `hard` từ trước, lệnh này thì không, dù cùng một loại file findings."
+      },
+      "review-tech-docs": {
+        "writes": [
+          { "path": "{refinement_dir}/{TICKET-ID}-tech-review-findings.yaml",
+            "mode": "merge", "creates": true, "regenerable": false, "when": "always",
+            "note": "Như /review-context: chứa quyết định reviewer, và mang thêm `sign_off` + `sign_off_gate` đọc từ @trace.sign_off của tech-doc." },
+          { "path": "tech-doc header — @trace.bdd_versions · @trace.sign_off  (+ áp fix vào thân doc)",
+            "mode": "merge", "regenerable": false, "when": "--resume",
+            "note": "Phase 2 áp fix, Phase 3 làm mới `@trace.bdd_versions` (CHỈ cho platform đã giải quyết T3b — platform còn finding open giữ số cũ CÓ CHỦ Ý, để cờ TECHDOC_STALE_VS_BDD của /validate-traces còn sáng) và thêm skeleton `@trace.sign_off` nếu vắng. `sign_off` là XÁC NHẬN CỦA NGƯỜI (be_team/fe_team/app_team/sa)." },
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-*.tsv — cột tech_doc_revision · last_updated",
+            "mode": "merge", "regenerable": true, "when": "--resume",
+            "note": "Phase 3, cho MỌI UC trong `@trace.ucs` và MỌI sổ platform. KHÔNG đụng `fe_tech_doc_revision` — cột đó do /generate-code --phase=integration sở hữu." }
+        ],
+        "has_human_content": true,
+        "why": "Cũng khai 'READ-ONLY — KHÔNG sửa target', nhưng `--resume` Phase 2–3 ghi vào THÂN tech-doc, HEADER tech-doc, và sổ TSV của mọi UC mà doc phủ. Đây là lệnh ghi rộng nhất trong nhóm tự-nhận-read-only."
+      },
+      "validate-traces": {
+        "writes": [
+          { "path": "{trace_dir}/trace-report.json  ·  {living_docs_dir}/trace-report.json",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Snapshot đầy đủ tại thời điểm chạy lần cuối; source of truth cho web dashboard. Dựng lại bằng cách chạy lại lệnh." },
+          { "path": "{trace_dir}/trace-history.jsonl",
+            "mode": "append", "regenerable": false, "when": "always",
+            "note": "⭐ ĐÂY LÀ CA SINH RA TRƯỜNG `regenerable`. Tmpl tự khai: 'AUTHORITATIVE, không regenerate được' · 'PHẢI commit' · sync.tmpl gọi là 'dữ liệu tích luỹ, không phải thứ sinh lại được'. Không ai gõ tay vào nó nên `has_human_content` trả lời false — ĐÚNG CHỮ, và để lọt đúng thứ mất là mất vĩnh viễn. Nó AN TOÀN chỉ vì `append`: đổi sang overwrite là R18 đỏ ngay." },
+          { "path": "./.trace-mirror/ (panel mirror)",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Bỏ qua hoàn toàn nếu {trace_dir} đã nằm trong workspace hiện tại." },
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv — row trạng thái",
+            "mode": "merge", "regenerable": true, "when": "--reconcile-code",
+            "note": "Step 5f. Điền row theo kết quả quét tag code + `has_verifies`. Chạy lại quét là có lại." },
+          { "path": "{trace_dir}/{domain}/{prd-slug}/_seams.tsv",
+            "mode": "merge", "regenerable": true, "when": "--reconcile-code",
+            "note": "Khớp dòng theo khoá (kind, name, consumer_uc) — KHÔNG khớp theo `artifact`, vì class/method đổi tên giữa hai lần chạy sẽ đẻ ra bản ghi ma. Giữ nguyên `owner_uc`/`binding` (do /generate-code sở hữu)." }
+        ],
+        "has_human_content": false,
+        "why": "Không ô nào cho người điền — nhưng KHÔNG PHẢI vì thế mà an toàn. Lệnh ở mức `none` là ĐÚNG, và lý do đúng là: mọi thao tác ghi `when: always` đều hoặc dựng lại được (trace-report.json, mirror) hoặc `append` (trace-history.jsonl); hai thao tác nguy hơn đều nằm sau `--reconcile-code`. Tmpl:58 tự phân biệt: 'Với một lệnh CHỈ ĐỌC thì đó là đốt thời gian. Với --reconcile-code (CÓ GHI) thì...'. Lời khai cũ 'read-only ... không đụng spec/code' là SAI — đã sửa 2026-09-16."
+      },
+      "generate-bdd": {
+        "writes": [
+          { "path": "{specs_dir}/{domain}/{prd-slug}/bdd/{platform}/{TICKET-ID}-UC{N}-{slug}.feature",
+            "mode": "overwrite", "regenerable": false, "when": "always", "human_content": true,
+            "note": "Mode F (gen lại TOÀN BỘ scenario) ghi đè mọi scenario đã có. `.feature` là ĐIỂM NEO của sổ trace: `sc_id` = {UC-ID}-SC{N} bị chép vào TSV, vào tag `@trace.verifies` trong code, và vào `.Test.md` — đánh số lại là phá cả bốn cùng lúc." },
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Tạo hoặc cập nhật, MỘT sổ cho mỗi platform — `sc_id` chỉ độc nhất trong (UC × platform), nên gộp là scenario platform này đè platform khác. Dựng lại được từ `.feature`." }
+        ],
+        "has_human_content": true,
+        "why": "BDD là spec ĐÃ DUYỆT, và mode F ghi đè toàn bộ. Sổ TSV thì ngược lại — suy từ `.feature`, dựng lại được."
+      },
+      "generate-tech-docs": {
+        "writes": [
+          { "path": "{tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md",
+            "mode": "merge", "regenerable": false, "when": "always", "human_content": true,
+            "note": "Ghi/mở rộng theo từng UC, có hỏi \"Cập nhật các section của UC này? (Y = merge/mở rộng · N = bỏ qua UC này)\". Doc chứa §4.5.6 Test Selectors do SA VIẾT TAY (xem /map-testids) và §12 GAP Register — cả hai không suy lại được từ BDD." }
+        ],
+        "has_human_content": true,
+        "why": "Cùng một file mà /map-testids đã phải chặn cứng vì §4.5.6. Lệnh này ghi rộng hơn — cả thân doc — nên không thể lỏng hơn."
+      },
+      "generate-design-spec": {
+        "writes": [
+          { "path": "{specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh từ PRD + figma/design source. Không có ô nào cho người điền, không trạng thái tích luỹ qua các lần chạy." }
+        ],
+        "has_human_content": false,
+        "why": "Ghi đè AN TOÀN theo hiện trạng đo 2026-09-16 — KHAI LẠI NẾU về sau designer/PO bắt đầu sửa tay vào file này. Khác /generate-bdd (spec đã duyệt) và /generate-tech-docs (§4.5.6 do SA viết): design-spec chưa có phần nào người sở hữu."
+      },
+      "generate-code": {
+        "writes": [
+          { "path": "{src_dir}/… mã nguồn theo layer + {UC-ID}MockApiAdapter.{ext} + real API adapter",
+            "mode": "merge", "regenerable": false, "when": "always", "human_content": true,
+            "note": "Dev SỬA TAY chính các file này. Đây là artifact đắt nhất trong toàn framework — và trước 2026-09-16 lệnh đứng ở mức `normal`, tức `--yes` ghi đè mã nguồn đã sửa tay TRONG IM LẶNG." },
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv — cột gen/impl",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Khớp row theo `sc_id`, chỉ đụng cột nó sở hữu. Liên-repo ở umbrella: trace_dir phân giải về {spec_source}/.trace." },
+          { "path": "{trace_dir}/{domain}/{prd-slug}/_seams.tsv",
+            "mode": "merge", "creates": true, "regenerable": true, "when": "always",
+            "note": "SỔ CHUNG của seam/stub liên-UC. Lệnh tự khai \"tạo file + header nếu chưa có\" — nó là lệnh DUY NHẤT tạo sổ này; /validate-traces chỉ merge \"nếu tồn tại\". Sở hữu cột `owner_uc`/`binding`. (Artifact này SÓT hẳn khỏi registry cho tới khi R22 bắt được, 2026-09-16.)" },
+          { "path": "./.trace-mirror/ (panel mirror, qua steps/trace-mirror.md)",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh lại được bất cứ lúc nào, luôn gitignore." }
         ],
         "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."
+        "why": "Ghi đè mã nguồn dev đã sửa tay. Cùng khuôn G77/G84 (lane QC và lane dev), nhưng ở artifact có giá trị cao nhất."
+      },
+      "define-product": {
+        "writes": [
+          { "path": "{product_definitions_dir}/{TICKET-ID}-{slug}.md",
+            "mode": "merge", "regenerable": false, "when": "always", "human_content": true,
+            "note": "Từng mục mang dấu `✅ PO xác nhận` hoặc `🤖 AI trích — chờ PO chốt`, và `Completed Phase` cho phép resume giữa chừng. Ghi đè là xoá cả vòng xác nhận của PO và đẩy discovery về phase 0." }
+        ],
+        "has_human_content": true,
+        "why": "Dấu `✅ PO xác nhận` là kết luận của NGƯỜI trên từng mục, không suy lại được. Guard chống-blitz của chính lệnh nói rõ: một phase chỉ tính là chốt khi MỌI item mang dấu đó."
+      },
+      "fix-bug": {
+        "writes": [
+          { "path": "mã nguồn — áp fix trên nhánh `fix/{TICKET_ID}-{description}`",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Sửa ĐIỂM (kèm `@trace.fixes`/`@trace.root_cause`), KHÔNG ghi đè file, và Phase 3 tự `git checkout -b` sang nhánh riêng trước khi sửa — nhánh đó là đường lùi. Fix suy được lại từ bug report + phân tích." },
+          { "path": "{lessons_path}",
+            "mode": "merge", "regenerable": false, "when": "confirm", "human_content": true,
+            "note": "Qua steps/capture-lesson.md, sau câu hỏi \"Ghi nó thành project lesson để không bị sinh lại? (Y/N)\". Đây là artifact DUY NHẤT của lệnh có phần người nhập tay — và nó CÓ ĐIỀU KIỆN." },
+          { "path": "{trace_dir}/…/{UC-ID}-{platform}.tsv — reset `dev_selftest`",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Hạ cờ về `not_run` vì code vừa đổi. Chạy /dev-run-test là có lại." },
+          { "path": "./.trace-mirror/", "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh lại được, luôn gitignore." }
+        ],
+        "has_human_content": true,
+        "why": "Ở mức `normal` CÓ CHỦ Ý. Lệnh sửa đúng thứ người dùng vừa yêu cầu nó sửa, trên một nhánh riêng, sau khi /dev-run-test đã báo đỏ — dựng cổng chặn ở đó là hỏi lại một việc vừa được yêu cầu. Artifact có phần người nhập tay (`{lessons_path}`) nằm sau `(Y/N)`, nên luật (A) không áp: xem `human_content` ở cấp artifact."
+      },
+      "report-bug": {
+        "writes": [
+          { "path": "{bug_reports_dir}/{BUG-ID}.md",
+            "mode": "create", "regenerable": false, "when": "always",
+            "note": "Lệnh tự khai `Output Artifacts: CREATED` — mỗi lần chạy một {BUG-ID} mới, rồi `git add` + `git commit` vào spec repo dùng chung. Không đè bản ghi cũ. Nội dung là quan sát của MỘT phiên, không dựng lại được — nhưng `create` nên không mất gì." }
+        ],
+        "has_human_content": false,
+        "why": "Chỉ TẠO file mới. Không ô nào cho người điền lúc sinh (người sửa sau thì sửa trên file đã commit, lệnh không quay lại đè)."
+      },
+      "propose-scenario": {
+        "writes": [
+          { "path": "{bdd_proposals_dir}/{UC-ID}-{slug}.md  ·  {prd_change_requests_dir}/{UC-ID}-{slug}.md",
+            "mode": "create", "regenerable": false, "when": "always",
+            "note": "Lệnh tự khai `created`. Case A → bdd-proposals (`/generate-bdd` tự chèn khi `Status: accepted`); Case B → prd-change-requests (PO phải đưa vào PRD trước). Cột `Status` do NGƯỜI đổi — nhưng lệnh không quay lại ghi đè file đã tạo." }
+        ],
+        "has_human_content": false,
+        "why": "Chỉ TẠO đề xuất mới. `Status: accepted` do người đặt về sau, và không lệnh nào trong framework ghi đè lại file đó."
+      },
+      "setup-ai-first": {
+        "writes": [
+          { "path": ".agent/project-context.yaml · CLAUDE.md · specs/domain-knowledge/business-dictionary.md · core-entities.md · các base dir",
+            "mode": "create", "regenerable": false, "when": "always",
+            "note": "⭐ CHỈ TẠO KHI CHƯA CÓ — tmpl nói ba lần: \"skip nếu đã tồn tại\", \"nếu chưa tồn tại\". File đã có thì lệnh KHÔNG đụng. Đây là lý do nó ở `normal` chứ không phải `hard`, dù artifact của nó (CLAUDE.md, project-context.yaml) là thứ người sửa tay nhiều nhất." }
+        ],
+        "has_human_content": false,
+        "why": "Artifact thì CÓ phần người nhập tay, nhưng lệnh KHÔNG BAO GIỜ ghi đè chúng — `mode: create`. Rủi ro nằm ở THAO TÁC, không ở artifact: đây chính là ca làm tôi dự đoán sai mức của lệnh này khi chưa đọc file."
+      },
+      "generate-spec-manifest": {
+        "writes": [
+          { "path": "{manifest_root}/spec-manifest.yaml",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "\"Ghi đè nếu tồn tại\" — và chính report của lệnh in: \"Sinh lại bất cứ lúc nào: /generate-spec-manifest\". Chỉ số ticket_id/domain/status/version/prd_path quét từ specs." }
+        ],
+        "has_human_content": false,
+        "why": "Chỉ mục thuần, suy 100% từ cây specs. Không ô nào cho người điền."
+      },
+      "sync": {
+        "writes": [
+          { "path": "{service.path}/.agent/project-context.yaml",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh từ cấu hình umbrella — dựng lại bằng cách chạy lại /sync." },
+          { "path": "{living_docs_dir}/trace-report.json (merged) + {panel_mirror}/",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Gộp report từ các service. KHÔNG copy `trace-history.jsonl` — tmpl nói rõ nó là \"dữ liệu tích luỹ, không phải thứ sinh lại được\"." },
+          { "path": "spec-manifest.yaml", "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Như /generate-spec-manifest." }
+        ],
+        "has_human_content": false,
+        "why": "Mọi artifact đều suy từ cấu hình umbrella + report của các service. Điểm đáng chú ý: lệnh CỐ Ý không đụng `trace-history.jsonl` — nó biết file đó không dựng lại được."
+      },
+      "learn": {
+        "writes": [
+          { "path": "{lessons_path}",
+            "mode": "merge", "regenerable": false, "when": "confirm", "human_content": true,
+            "note": "Qua steps/capture-lesson.md. Lesson là GUARDRAIL do người chốt, tích luỹ qua nhiều phiên. Lệnh có 4 câu hỏi `(Y/N)` trước khi ghi." }
+        ],
+        "has_human_content": true,
+        "why": "Cùng artifact và cùng đường với /review-code · /debug · /fix-bug. Ghi nằm sau `(Y/N)` nên `normal` là đúng mức — thêm CHECKPOINT nữa là hỏi hai lần cho một hành động."
+      },
+      "update-framework": {
+        "writes": [
+          { "path": ".agent/ (copy core/ → .agent/, vô điều kiện) + .claude/commands/ shortcuts",
+            "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "⭐ ĐÈ THẬT, nhưng CỨU ĐƯỢC: bản cũ lưu ở `.agent/.overwritten-{version}-{date}/` từ v0.4.2, và lệnh TỰ IN cảnh báo kèm lệnh `diff` khi thư mục đó xuất hiện. Nội dung `.agent/` là MIRROR sinh từ package — dựng lại bằng cách cài lại. Ba chỗ KHÔNG bị đè: CLAUDE.md · project-context.yaml · project-lessons.md." }
+        ],
+        "has_human_content": false,
+        "why": "Ở mức `normal` là ĐÚNG dù nó ghi đè: mất có đường lùi (`.overwritten-*`), có báo, và `.agent/` là mirror dựng lại được. Đây là ca chứng minh `regenerable` phải hỏi \"dựng lại được không\", KHÔNG phải \"có đè không\"."
+      },
+      "dev-run-test": {
+        "writes": [
+          { "path": "{trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv — cột dev_selftest · dev_selftest_at",
+            "mode": "merge", "regenerable": true, "when": "always",
+            "note": "Khớp row theo `sc_id`, giữ nguyên cột của /dev-gen-test và /qc-run-script. Chạy lại test là có lại." },
+          { "path": "./.trace-mirror/", "mode": "overwrite", "regenerable": true, "when": "always",
+            "note": "Sinh lại được, luôn gitignore." }
+        ],
+        "has_human_content": false,
+        "why": "Chỉ ghi kết quả chạy vào sổ. Việc SỬA test khi expectation sai là dev làm tay, không phải lệnh này ghi."
       }
     },
     "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.",
+      "$comment": [
+        "RỖNG TỪ 2026-09-16 (N3) — `enrolled` phủ 32/33 lệnh; lệnh thứ 33 (`dev-smoke-test`) nằm",
+        "ở `non_writers` vì nó KHÔNG ghi file nào. Đây là lần đầu danh sách nợ này rỗng kể từ khi",
+        "khối artifact_writers ra đời.",
+        "",
+        "GIỮ KHOÁ NÀY LẠI, KHÔNG XOÁ: lệnh mới thêm về sau mà chưa rà phải có chỗ để KHAI RA, thay",
+        "vì rơi vào mặc định `normal` trong im lặng — đúng lỗ hổng đã xảy ra bốn lần (G67·G77·G78·G79).",
+        "",
+        "⚠️ ĐÍNH CHÍNH (2026-09-16): bản N2 của $comment này khai `dev-smoke-test` 'Tạo PR và link",
+        "tới ticket — một tác động RA NGOÀI repo'. SAI. Dòng đó ở steps/report-footer.md:113 nằm",
+        "trong bảng LÀM GÌ TIẾP THEO — nó nói với NGƯỜI DÙNG, không mô tả hành vi lệnh. Bài học:",
+        "một dòng trong tài liệu chỉ là bằng chứng về hành vi nếu nó nằm trong phần MÔ TẢ HÀNH VI."
+      ],
+      "cmds": []
+    },
+    "non_writers": {
+      "$comment": [
+        "LỆNH KHÔNG GHI FILE NÀO — rà rồi, kết luận là không có gì để khai (N3 · 2026-09-16).",
+        "",
+        "VÌ SAO CẦN DANH SÁCH NÀY, KHÔNG PHẢI BỎ TRỐNG: một lệnh vắng mặt ở CẢ `enrolled` LẪN",
+        "`pending_enrollment` trông y hệt một lệnh bị quên. Ghi ra đây biến 'không có gì' thành một",
+        "KẾT LUẬN kiểm chứng được — cùng lập luận đã bắt `why` phải khai cả khi false (G79).",
+        "",
+        "R18 kiểm: lệnh ở đây KHÔNG được đồng thời ở `enrolled`, và tmpl phải tồn tại."
+      ],
       "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"
-      ]
-    }
-  },
+        "dev-smoke-test"
+      ],
+      "why": {
+        "dev-smoke-test": "Rà bản ĐÃ ĐÚC (core/commands/dev-smoke-test.md): không có dòng ghi file nào, và không include step ghi-file nào (chỉ context-loader · gate · report-footer). Nó CHẠY test khói và in kết quả; việc tạo PR là BƯỚC TIẾP THEO gợi ý cho người dùng, không phải hành vi của lệnh."
+      }
+    }  },
   "testid_fourth_leg": {
     "$comment": [
       "CHÂN THỨ TƯ CỦA HỢP ĐỒNG TEST-ID: §4.5.6 ↔ *.Test.md (G64).",
@@ -2273,7 +2795,7 @@
       "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-run-script  → 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:",
@@ -2295,7 +2817,7 @@
       "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.",
+      "why": "LỚP CI cho chân thứ tư (G76). Guard ở /qc-review-testcase + /qc-design-script 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.",
@@ -2304,11 +2826,11 @@
     },
     "checked_by": [
       {
-        "cmd": "qc-review",
+        "cmd": "qc-review-testcase",
         "level": "warn"
       },
       {
-        "cmd": "qc-run-test",
+        "cmd": "qc-design-script",
         "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."
       }
@@ -2323,7 +2845,7 @@
       "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)",
+      "    qc_status = not_run   ⇒ CHẠY LẠI  (/qc-run-script)",
       "    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",
@@ -2440,14 +2962,22 @@
         "on_stale": "warn"
       },
       {
-        "cmd": "qc-review",
+        "cmd": "qc-review-testcase",
         "checks": [
           "test-cases/*.Test.md"
         ],
         "on_stale": "warn"
+      },
+         {
+        "cmd": "qc-run-manualtest",
+        "checks": [
+          "test-cases/*.Test.md"
+        ],
+        "on_stale": "block_positive_assertion",
+        "$note": "Cùng luật với /qc-run-script: TC lỗi thời thì kết quả chạy TAY cũng không được ghi `pass`. Ở test tay guard này còn quan trọng hơn — lời khẳng định của người chạy là bằng chứng duy nhất, nên lớp chặn cơ học là thứ duy nhất đứng giữa một cái gật đầu thiện chí và một dòng `pass` sai trong sổ."
       },
       {
-        "cmd": "qc-run-test",
+        "cmd": "qc-design-script",
         "checks": [
           "test-cases/*.Test.md"
         ],
@@ -2537,7 +3067,8 @@
         "field": "status",
         "actors": [
           "dev-run-test",
-          "qc-run-test"
+          "qc-run-script",
+          "qc-run-manualtest"
         ],
         "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."
       },