@educa-corp/sdd-framework 0.9.0 → 0.9.1

package/bin/lint-trace.js

@@ -681,6 +681,57 @@ function expandImplements(value) {
   return out;
 }
 
+/**
+ * Thu mọi `@trace.implements` của một file, XỬ ĐƯỢC tag trải nhiều dòng.
+ *
+ * Vì sao cần (phát hiện 2026-08-27, ngay lượt dùng T14 đầu tiên trên dữ liệu thật):
+ * quy ước thực tế viết danh sách dài xuống nhiều dòng comment —
+ *
+ *     // @trace.verifies=LESS-06-UC1-SC1, LESS-06-UC1-SC2, LESS-06-UC1-SC3,
+ *     //   LESS-06-UC1-SC4, LESS-06-UC1-SC5, LESS-06-UC1-SC9,
+ *
+ * Bản đầu của T14 đọc theo TỪNG DÒNG nên chỉ thấy 3 SC đầu và bỏ hết phần sau. Nó sai
+ * theo hướng an toàn (báo thiếu, không báo oan) nhưng vẫn là mù — và mù đúng ở những UC
+ * có nhiều scenario nhất, tức đúng chỗ cần nhìn nhất.
+ *
+ * Luật nối dòng: giá trị kết thúc bằng `,` ⇒ đọc tiếp các dòng sau **chỉ khi** dòng đó
+ * thuần là danh sách id (cho phép tiền tố comment). Gặp dòng khác ⇒ dừng. Chặt như vậy để
+ * một dấu phẩy cuối câu văn xuôi không kéo cả đoạn prose vào làm sc_id rác.
+ */
+const ID_LIST_LINE = /^\s*(?:\/{2,}|\/\*+|\*|#)?\s*(?:[A-Z0-9][A-Z0-9-]*-UC\d+-(?:SC|BR|AC)\d+|(?:SC|BR|AC)\d+)\s*(?:,\s*(?:[A-Z0-9][A-Z0-9-]*-UC\d+-(?:SC|BR|AC)\d+|(?:SC|BR|AC)\d+)\s*)*,?\s*(?:\*\/)?\s*$/;
+
+function collectImplements(txt) {
+  const out = [];
+  const lines = txt.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    // matchAll, KHÔNG exec: một dòng comment có thể mang NHIỀU tag ngăn bởi `·`, và
+    // `exec` trên regex không-global chỉ trả về match ĐẦU TIÊN ⇒ mất tag thứ hai.
+    //
+    // Và group phải DỪNG trước `@trace.` kế tiếp (negative lookahead). Không có nó thì
+    // group tham lam nuốt luôn tag thứ hai, `matchAll` chỉ thấy MỘT match, và tag sau bị
+    // mất trong im lặng — bug từ bản đầu của T14: bản đó chỉ CẮT giá trị cho khỏi sinh
+    // sc_id rác, nó không bao giờ LẤY LẠI tag bị nuốt.
+    const hits = [...lines[i].matchAll(/@trace\.implements\s*[=:]?\s*((?:(?!@trace\.)[^\n\r*])*)/g)];
+    if (!hits.length) continue;
+    let j = i + 1;
+    hits.forEach((m, k) => {
+      // Lookahead ở trên đã chặn tag kế tiếp; `·` và khoảng trắng dư do expandImplements bỏ.
+      let buf = m[1];
+      // CHỈ tag cuối cùng của dòng mới có thể trải tiếp — các tag trước nó đã bị cắt ở
+      // `@trace.` nên không bao giờ kết thúc bằng dấu phẩy.
+      if (k === hits.length - 1) {
+        while (buf.trimEnd().endsWith(',') && j < lines.length && ID_LIST_LINE.test(lines[j])) {
+          buf += ' ' + lines[j].replace(/^\s*(?:\/{2,}|\/\*+|\*|#)?\s*/, '').replace(/\*\/\s*$/, '');
+          j++;
+        }
+      }
+      out.push(...expandImplements(buf));
+    });
+    i = j - 1;
+  }
+  return out;
+}
+
 function lintCodeVsLedger() {
   if (!CODE_DIRS.length) {
     infos.push(`T14 BỎ QUA — không có --code nên chưa đối chiếu code với sổ. ` +
@@ -715,18 +766,11 @@ function lintCodeVsLedger() {
       try { txt = fs.readFileSync(p, 'utf8'); } catch { continue; }
       if (!txt.includes('@trace.implements')) continue;
       filesScanned++;
-      // Một dòng comment có thể mang NHIỀU tag ngăn bởi `·` — cắt trước tag kế tiếp,
-      // không thì giá trị nuốt cả dòng và sinh sc_id rác.
-      for (const m of txt.matchAll(/@trace\.implements\s*[=:]?\s*([^\n\r*]*)/g)) {
-        let v = m[1];
-        const cut = v.indexOf('@trace.');
-        if (cut >= 0) v = v.slice(0, cut);
-        for (const { uc, unit } of expandImplements(v)) {
-          if (!unit.startsWith('SC')) continue;      // BR/AC là tag hợp lệ, không phải scenario
-          const id = `${uc}-${unit}`;
-          if (!tagged.has(id)) tagged.set(id, new Set());
-          tagged.get(id).add(rel(p));
-        }
+      for (const { uc, unit } of collectImplements(txt)) {
+        if (!unit.startsWith('SC')) continue;        // BR/AC là tag hợp lệ, không phải scenario
+        const id = `${uc}-${unit}`;
+        if (!tagged.has(id)) tagged.set(id, new Set());
+        tagged.get(id).add(rel(p));
       }
     }
   };

package/bin/trace-schema.json

@@ -1855,6 +1855,11 @@
     ]
   },
   "forbidden_patterns": [
+    {
+      "pattern": "`integration`",
+      "reason": "Giá trị cột `fe_phase` là `integrated` (CÓ hậu tố -ed). Dạng không -ed chỉ thuộc về CỜ `--phase=integration`. Ghi sai vào sổ thì `--lint-trace` T3 báo lỗi enum, VÀ `fe_integrated` ở /validate-traces Step 7 đếm `integrated` nên counter mãi bằng 0 trong im lặng — đúng hình dạng G1 (cờ im lặng). R6 ĐÃ DỰ ĐOÁN ca này (comment của nó: 'G19 là ca này') và chỉ đúng công cụ là forbidden_patterns — nhưng chưa ai khai. Nó tái diễn thật ở 0.9.0: bốn chỗ trong hai lệnh ghi giá trị cột là dạng không -ed, và CHÍNH validate-traces.tmpl tự mâu thuẫn: một dòng bảo ghi dạng đó, dòng khác đếm `integrated`.",
+      "gap": "G19/G61"
+    },
     {
       "pattern": "bdd/{UC-ID}.feature",
       "reason": "@trace.source thiếu segment {platform}. Layout thật: bdd/{platform}/{UC-ID}-{slug}.feature",

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.0
+0.9.1

package/core/commands/generate-code.md

@@ -776,7 +776,8 @@ Cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{@trace.platform}.ts
 | `bdd_version` | `@trace.bdd_version` từ header `.feature` |
 | `tech_doc_revision` | `@trace.revision` từ tech-doc gộp `{TICKET-ID}-tech-design.md` (§4 backend đã điều khiển codegen của UC này), hoặc `—` nếu chưa có doc |
 | `fe_tech_doc_revision` | `@trace.revision` của cùng tech-doc gộp, ghi khi sinh FE có wire adapter theo §4.5.4 (`--phase=integration` **hoặc** `fe_full`); `—` cho BE, hoặc cho FE `--phase=ui` / chưa có §4.5.4 |
-| `fe_phase` | `ui` nếu `--phase=ui` \| `integration` nếu `--phase=integration` **hoặc** `fe_full` (đều đã wire real adapter) \| `—` cho BE |
+| `fe_phase` | `ui` nếu `--phase=ui` \| **`integrated`** nếu `--phase=integration` **hoặc** `fe_full` (đều đã wire real adapter) \| `—` cho BE |
+> ⚠️ Giá trị cột là **`integrated`** — có hậu tố **-ed**. Dạng không -ed chỉ thuộc về **cờ** `--phase=integration`, không bao giờ là giá trị của cột; vocabulary của cột chỉ có `ui` \| `integrated` (`trace-schema.json` → `vocabularies.fe_phase`). Ghi sai giá trị thì `--lint-trace` T3 báo lỗi, và `fe_integrated` ở `/validate-traces` Step 7 đếm `integrated` nên sẽ **mãi bằng 0 trong im lặng**.
 | `last_updated` | hôm nay `YYYY-MM-DD` |
 
 Giữ nguyên mọi cột khác (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`) — **trừ ngoại lệ có kiểm soát ngay dưới đây**: khi logic vừa đổi thật (lấp stub, hoặc sửa method vì `DRIFT`), 4 cột nghiệm thu `dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at` **phải bị hạ** về "chưa biết". Giữ một `pass` đã hết hiệu lực là báo cáo sai, không phải tôn trọng quyền sở hữu cột.
@@ -908,7 +909,7 @@ Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 Files: created={N}, extended={M}, filled={F} stub, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
 Phase    : {UI (mock layer) | Integration (real API) | FE full (UI + real API) | BE full}
-fe_phase : {ui | integration (—phase=integration | fe_full) | —}
+fe_phase : {ui | integrated (--phase=integration | fe_full) | —}
 Figma    : {Dev Mode MCP local (grounded) | ⚠️ chỉ link web + text spec (không có MCP local) | n/a cho BE}   ← chỉ UI FE/App
 
 Next:

package/core/commands/validate-traces.md

@@ -190,6 +190,30 @@ Nhiều cờ scope cùng lúc → **DỪNG**, báo lỗi: chúng loại trừ nh
 
 `--prd`/`--uc` không phân giải được về một package/UC có thật → **DỪNG** và liệt kê ứng viên. **KHÔNG** âm thầm rơi về `all` (chạy toàn bộ khi người ta xin một phần là đốt 30 phút không ai muốn) và **KHÔNG** âm thầm audit rỗng (báo cáo "sạch" trên 0 row).
 
+**Token TRẦN (không mở đầu bằng `--`)** — vd `/validate-traces --reconcile-code LESS-06`:
+
+| Token trần trông như | Xử |
+|---|---|
+| **UC-ID** (`{TICKET}-UC{n}`) | coi là `--uc {token}` |
+| **TICKET-ID** phân giải được về đúng **một** feature-package | coi là `--prd {token}` |
+| không phân giải được, hoặc khớp **nhiều** package | **DỪNG**, liệt kê ứng viên |
+| có **cả** token trần **và** một cờ scope | **DỪNG** — hai nguồn phạm vi, không tự chọn hộ |
+
+Hai hàng đầu **phải in một dòng** nói rõ đã tự suy, để người dùng thấy mình vừa được hiểu thế nào:
+```
+ⓘ Hiểu `{token}` là `--prd {token}` ({domain}/{prd-slug}). Gõ cờ tường minh nếu ý khác.
+```
+
+> **Vì sao không để token trần rơi về `all` (phát hiện 2026-08-27, lượt dùng `--reconcile-code` đầu tiên).**
+> Gate Bước 1 loại mọi token `--` khỏi phần resolve target, và lệnh này **không có target file** — nên
+> token trần trước đây **bị bỏ hoàn toàn** ⇒ `scope` = `all`. Người dùng gõ `--reconcile-code LESS-06`
+> tin rằng đang chạy hẹp một PRD, trong khi lệnh sẽ **GHI vào sổ của cả 20+ PRD**, gồm cả phần của PO
+> khác. Đây đúng điều chính step này cấm hai dòng ở trên — *"KHÔNG âm thầm rơi về `all`"* — chỉ khác là
+> lỗ vào bằng cửa *"không có cờ nào"* thay vì cửa *"cờ không phân giải được"*.
+>
+> Với một lệnh **chỉ đọc** thì đó là đốt thời gian. Với `--reconcile-code` (có GHI) thì đó là ghi ra
+> ngoài phạm vi mà người dùng nghĩ mình đã yêu cầu — hạng nặng hơn hẳn.
+
 Lưu `scope` — mọi step sau dùng nó:
 
 | Step | Hẹp thế nào |
@@ -621,7 +645,7 @@ Không đụng `dev_selftest`/`qc_status` (luật G28 không áp: **không có l
 |---|---|
 | `implemented_by` | tên class/hàm mang `@trace.implements` cho SC đó (nhiều file → nối bằng `,`, đúng khuôn `/generate-code` đang ghi) |
 | `gen_ver` | copy `spec_ver` của **chính row đó** *(không phải version hiện tại của `.feature` — code sinh ra từ bản nào thì `spec_ver` lúc này là bản đó; Step 2 vừa đồng bộ nó)* |
-| `fe_phase` | `integration` nếu file code có wire adapter thật theo §4.5.4 · `ui` nếu chỉ có mock · `—` cho `system`. **Không suy được** → để `—`, đừng đoán |
+| `fe_phase` | **`integrated`** nếu file code có wire adapter thật theo §4.5.4 · `ui` nếu còn `@trace.mock_for`/mock adapter · `—` cho `system`. **Không suy được** → để `—`, đừng đoán. *(Vocabulary chỉ có `ui` \| `integrated` — nhớ hậu tố **-ed**. Dạng không -ed thuộc về cờ `--phase=integration`, không phải cột này.)* |
 | `test_count` · `test_classes` | **CHỈ khi `has_verifies` = true** (Step 2b đã thu). Số test + tên class lấy từ file mang `@trace.verifies`. `has_verifies` = false → **để trống**, tuyệt đối không điền 0-giả hay tên class phỏng đoán |
 
 > ### ⚠️ Luật cứng: KHÔNG set `status`
@@ -654,7 +678,7 @@ Không đụng `dev_selftest`/`qc_status` (luật G28 không áp: **không có l
       {UC-ID}-{platform}.tsv:{dòng}  {sc_id}
         implemented_by ← {ClassName.method}      (từ {file}:{dòng})
         gen_ver        ← {spec_ver}
-        fe_phase       ← {ui | integration | —}
+        fe_phase       ← {ui | integrated | —}
         test_count     ← {n} · test_classes ← {…}   (từ @trace.verifies ở {file})   [hoặc: bỏ trống — không có @trace.verifies]
    ```
    Ghi bù im lặng là ghi bù không kiểm chứng được.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"