@educa-corp/sdd-framework 0.7.0 → 0.7.2

package/bin/lint-trace.js

@@ -155,6 +155,63 @@ function readLines(file) {
   return fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n').split('\n');
 }
 
+// ── T13 — hai điều kiện bảo vệ sổ có KIỂM ĐƯỢC không ─────────────────────────
+//
+// T10 (luật merge) và T11 (bị gitignore) đều hỏi `git`. Trước T13, khi không hỏi được
+// thì cả hai `catch { return; }` — IM LẶNG. Và im lặng ở đây tệ hơn nó nghe: gate-trace
+// G0 lọc warns theo rule id, không thấy gì thì in ra
+//     "✅ G0 sổ được bảo vệ — nằm trong git · git biết cách gộp (2/2 điều kiện)"
+// tức KHẲNG ĐỊNH sổ được bảo vệ trên bằng chứng chưa bao giờ được thu. Cùng hình dạng
+// G55 (`pass` không có quyền khẳng định).
+//
+// Ca thường gặp nhất KHÔNG phải hiếm: image CI tối giản. `node:20-alpine` và
+// `node:20-slim` đều KHÔNG có git — tức chính môi trường mà cổng này tồn tại để chạy.
+//
+// Ba trạng thái, phân biệt có chủ ý:
+//   ok           → hỏi được, T10/T11 chạy bình thường
+//   no-binary    → không có `git` ⇒ KHÔNG BIẾT sổ có được bảo vệ hay không
+//   not-a-repo   → có git nhưng sổ không nằm trong repo nào ⇒ nó KHÔNG được commit
+// Hai trạng thái sau đều phát T13. Gate nâng T13 thành chặn (schema →
+// gate.config_preconditions.promote_lint_rules) — pre-push NHẮC, CI CHẶN, y như T10/T11.
+// Thụt lề cho dòng hint nhiều dòng — trùng khuôn của err()/warn().
+const NL = String.fromCharCode(10) + "        ";
+let _gitState = null;
+function gitState(sampleFile) {
+  if (_gitState) return _gitState;
+  const cp = require('child_process');
+  const q = (args, opts) => cp.spawnSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'ignore', 'ignore'], ...opts });
+  const v = q(['--version']);
+  if (v.error || v.status !== 0) return (_gitState = 'no-binary');
+  const dir = sampleFile ? path.dirname(sampleFile) : '.';
+  const r = q(['rev-parse', '--git-dir'], { cwd: fs.existsSync(dir) ? dir : '.' });
+  if (r.error || r.status !== 0) return (_gitState = 'not-a-repo');
+  return (_gitState = 'ok');
+}
+
+function lintGitEvaluable(sampleFile) {
+  const st = gitState(sampleFile);
+  if (st === 'ok') return true;
+  const where = rel(sampleFile || TRACE_DIRS[0]);
+  if (st === 'no-binary') {
+    warn('T13', where,
+         'KHÔNG kiểm được điều kiện bảo vệ sổ — môi trường này không có binary `git`',
+         ['T10 (luật merge) và T11 (bị gitignore) đều phải hỏi git. Không hỏi được thì hai điều',
+          'kiện đó KHÔNG được đánh giá — và "không biết" KHÔNG PHẢI "sạch".',
+          'Ca thường gặp nhất: image CI tối giản. node:*-alpine và node:*-slim đều KHÔNG có git.',
+          'Sửa:  image: node:20        (bản Debian — có git sẵn)',
+          '  hoặc apk add --no-cache git   /   apt-get install -y git'].join(NL));
+    return false;
+  }
+  warn('T13', where,
+       'sổ trace KHÔNG nằm trong một repo git nào — nó không được version control',
+       ['Sổ trace phải commit: nó không regenerate được, và trace-history.jsonl là dữ liệu',
+        'tích luỹ — mất là mất vĩnh viễn.',
+        'Nếu đây là bản copy tạm để kiểm thì bỏ qua được. Trong CI thì KHÔNG: nghĩa là repo',
+        'chưa được clone đúng, hoặc sổ nằm trong submodule chưa clone',
+        '(GitLab: GIT_SUBMODULE_STRATEGY=recursive · GitHub: submodules: recursive).'].join(NL));
+  return false;
+}
+
 // ── T7 — marker conflict git ──────────────────────────────────────────────────
 //
 // Chạy TRƯỚC mọi rule khác và trên MỌI file: một marker lọt vào TSV làm T1/T2 báo
@@ -587,8 +644,12 @@ for (const dir of TRACE_DIRS) {
     }
   }
 
-  if (sampleForAttr) lintMergeAttr(sampleForAttr);
-  lintGitTracked(abs);
+  // T13 TRƯỚC T10/T11: nếu không hỏi được git thì hai rule kia không có gì để phán, và
+  // im lặng ở đó làm gate G0 khẳng định "sổ được bảo vệ" trên bằng chứng không tồn tại.
+  if (lintGitEvaluable(sampleForAttr || abs)) {
+    if (sampleForAttr) lintMergeAttr(sampleForAttr);
+    lintGitTracked(abs);
+  }
 }
 
 // ── Report ────────────────────────────────────────────────────────────────────
@@ -596,7 +657,7 @@ for (const dir of TRACE_DIRS) {
 if (AS_JSON) {
   console.log(JSON.stringify({
     ok: errors.length === 0,
-    scanned, trace_dirs: foundDirs, errors, warns, infos,
+    scanned, trace_dirs: foundDirs, git_state: _gitState, errors, warns, infos,
   }, null, 2));
   process.exit(errors.length && !WARN_ONLY ? 1 : 0);
 }

package/bin/self-check.js

@@ -695,13 +695,16 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
 {
   const inv = (schema.gate || {}).audit_invalidating_tags;
   if (inv) {
-    const rel = inv.ci_template;
-    if (!rel) {
-      err('R10', '`gate.audit_invalidating_tags` thiếu `ci_template` — không biết canh file nào');
-    } else {
+    // MỖI template CI phải grep đủ 7 tag — không chỉ bản GitHub. Một bản dịch (GitLab…)
+    // không được canh mà tụt lại sau schema thì grep không khớp gì ⇒ job LUÔN XANH.
+    const rels = inv.ci_templates || (inv.ci_template ? [inv.ci_template] : []);
+    if (!rels.length) {
+      err('R10', '`gate.audit_invalidating_tags` thiếu `ci_templates` — không biết canh file nào');
+    }
+    for (const rel of rels) {
       const abs = path.join(ROOT, rel);
       if (!fs.existsSync(abs)) {
-        err('R10', `\`audit_invalidating_tags.ci_template\` trỏ tới ${rel} — file không tồn tại`,
+        err('R10', `\`audit_invalidating_tags.ci_templates\` trỏ tới ${rel} — file không tồn tại`,
             'Template đổi tên/bị xoá? Không có nó thì lỗ "sửa code mà không audit lại" hở lại.');
       } else {
         const yml = fs.readFileSync(abs, 'utf8');

package/bin/trace-schema.json

@@ -1107,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)."
@@ -1233,6 +1259,10 @@
         "Cùng cách phân vai G39 đã chọn cho pre-push vs CI."
       ],
       "promote_lint_rules": [
+        {
+          "rule": "T13",
+          "why": "KHÔNG KIỂM ĐƯỢC hai điều kiện kia — thiếu binary `git`, hoặc sổ không nằm trong repo git nào. Đây là loại THỨ TƯ, khác cả ba loại còn lại: không phải 'đang có cái sai' (🔴), không phải 'nợ' (🟠), cũng không phải 'bảo vệ đang tắt' (T10/T11) — mà là 'KHÔNG BIẾT bảo vệ có bật hay không'. Trước T13, ca này làm G0 in ra `sổ được bảo vệ — 2/2 điều kiện`: một lời KHẲNG ĐỊNH trên bằng chứng chưa bao giờ được thu, tệ hơn im lặng (cùng hình dạng G55). Ca thường gặp nhất là CI dùng image tối giản — node:*-alpine và node:*-slim đều KHÔNG có git — tức chính môi trường mà cổng này tồn tại để chạy."
+        },
         {
           "rule": "T11",
           "why": "sổ trace đang bị gitignore — nó KHÔNG được lưu vào git, mất là mất toàn bộ (G29)"
@@ -1343,7 +1373,17 @@
         "self-check R10 canh templates/ci/trace-gate.yml có nhắc đủ 7 tag này. Tag đổi tên mà",
         "file CI không biết ⇒ grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù im lặng."
       ],
-      "ci_template": "templates/ci/trace-gate.yml",
+      "$ci_templates_comment": [
+    "MỖI file CI phải grep đủ 7 tag. Trước v0.7.2 chỉ có bản GitHub Actions được canh —",
+    "nên khi một team dịch sang GitLab, bản dịch KHÔNG được rule nào canh, và nếu nó tụt",
+    "lại sau schema thì grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù trong im lặng. Đúng",
+    "lỗi R10 tồn tại để chặn, chỉ ở một file khác loại. Thêm template CI mới thì THÊM VÀO",
+    "danh sách này ngay — R10 canh từng file."
+   ],
+   "ci_templates": [
+    "templates/ci/trace-gate.yml",
+    "templates/ci/trace-gate.gitlab-ci.yml"
+   ],
       "tags": [
         {
           "tag": "@trace.implements",
@@ -1614,8 +1654,8 @@
       "khớp sổ ⇒ PASS · require-fresh-audit thấy PR không chạm tag ⇒ không đòi audit. Cả ba",
       "tầng xanh, và cả ba ĐÚNG theo định nghĩa của chính chúng.",
       "",
-      "Và G54 không chỉ CHO PHÉP sửa tay — nó ĐẨY người dùng về đó: /generate-prd chỉ có một",
-      "cổng chặn-cứng rồi vẫn ghi đè (mất changelog, đánh số lại BR) · /extend-prd chỉ",
+      "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.",

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.7.0
+0.7.2

package/core/commands/amend-prd.md

@@ -10,8 +10,9 @@
 > | **PRD đã có, PO muốn ĐỔI một yêu cầu đang đúng cú pháp** | **`/amend-prd`** | **Edit tại chỗ** — output **KHÔNG** phải superset |
 >
 > **Vì sao phải là lệnh riêng (GAPS-v4 G54).** Ba lệnh kia đều **từ chối đúng việc này**:
-> `/generate-prd` chỉ có một cổng chặn-cứng rồi vẫn ghi đè (mất changelog, **đánh số lại BR**,
-> phá `@trace.business_rules` trong mọi `.feature` đã sinh) · `/extend-prd` chỉ **add-only**, luật
+> `/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"* — vì ghi đè mất changelog, **đánh số lại BR**, phá `@trace.business_rules` trong mọi
+> `.feature` đã sinh, cả ba không hoàn tác được) · `/extend-prd` chỉ **add-only**, luật
 > Bước 5 §3 đòi output là *"superset chặt"* · `/refine-prd` tự cấm đụng section nào không được một
 > finding trỏ tới, và findings sinh từ việc soi PRD hiện có nên **không có đường nào để một ý định
 > MỚI của PO đi vào**.

package/core/commands/dev-run-test.md

@@ -338,7 +338,7 @@ Sau khi chạy, lưu kết quả vào **TSV authoritative** trong service để
 report Living Docs ở spec module (qua `/sync` + `/validate-traces`). Các file test
 ở lại trong service — chỉ *status* của lần chạy được report.
 
-Cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (`{platform}` = platform của code/`.feature` đang test — `system` cho backend, `web`/`app` cho FE/App; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp `sc_id` qua tag
+Cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (`{platform}` = platform của code/`.feature` đang test — `system` cho backend, mọi platform khác (`web`/`app`/`webview`/…) cho client; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp `sc_id` qua tag
 `@trace.verifies={UC-ID}-SC{N}` của test). *(Umbrella + `spec_source`: `trace_dir` là `{spec_source}/.trace` — test chạy từ `service_root` nhưng update `dev_selftest` ghi vào **spec repo**; commit/push spec submodule cho nó.)*
 
 ### ĐỌC cột `status` của row TRƯỚC KHI GHI *(bắt buộc)*

package/core/commands/generate-bdd.md

@@ -222,11 +222,14 @@ Hỏi người dùng chọn platform target:
 
 ```
 BDD này dành cho platform nào?
-  1. web    — FE/Web (React, Next.js, Angular, Vue, Nuxt)
-  2. app    — Mobile (Flutter, React Native, iOS, Android)
-  3. system — System/BE BDD (tổng hợp từ web + app BDD có sẵn)
+  1. web     — FE/Web trong browser (React, Next.js, Angular, Vue, Nuxt)
+  2. app     — Mobile native (Flutter, React Native, iOS, Android)
+  3. webview — Bundle web NHÚNG trong app native (Phaser game, mini-app)
+  4. system  — System/BE BDD (tổng hợp từ BDD client có sẵn)
 ```
 
+*Chỉ hiện những platform project thực sự dùng: nếu `services.{domain}` là map-theo-platform (context-loader 2b) thì lấy đúng các sub-key của nó làm danh sách; ngược lại hiện đủ bốn. `webview` là một **delivery surface** riêng — không phải `web` (browser) và không phải `app` (native) — nên nó có BDD, design-spec và sổ trace riêng.*
+
 Chờ người dùng chọn. Set `active_platform` = giá trị đã chọn.
 
 **Output path (spec repo mode):**
@@ -244,7 +247,7 @@ Chờ người dùng chọn. Set `active_platform` = giá trị đã chọn.
 
 ## System BDD Synthesis (active_platform = system)
 
-*Chỉ áp dụng khi platform = system. Bỏ qua với web và app.*
+*Chỉ áp dụng khi platform = `system`. Bỏ qua với mọi platform client (`web`/`app`/`webview`/…).*
 
 ### Step S0 — Brownfield Check
 
@@ -439,7 +442,7 @@ Umbrella mode không hỏi platform (khác spec repo mode) — nó **suy** từ
 
 ## Design Spec — Gate & Load (chỉ FE/App)
 
-*Chỉ chạy khi target platform là FE/App — spec mode: `active_platform ∈ {web, app, app-ios, app-android}`; umbrella mode: `active_module` là module FE/App (react/nextjs/vue/nuxt/angular/flutter/react-native/ios-swiftui/android-compose). Bỏ qua HOÀN TOÀN với `system` và backend/brownfield.*
+*Chỉ chạy khi target platform là FE/App — spec mode: `active_platform` là platform client (mọi giá trị **trừ** `system` — `web`, `app`, `webview`, `app-ios`, `app-android`, …); umbrella mode: `active_module` là module FE/App (react/nextjs/vue/nuxt/angular/flutter/react-native/ios-swiftui/android-compose). Bỏ qua HOÀN TOÀN với `system` và backend/brownfield.*
 
 **1. Định vị design-spec của platform:**
 `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
@@ -795,7 +798,7 @@ In danh sách SC được bump vào report cuối để người dùng biết c
 
 ## Write Trace State
 
-Sau khi sinh tất cả file `.feature`, tạo hoặc cập nhật **sổ trace theo platform** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` cho mỗi UC — một sổ riêng cho `system` / `web` / `app`. Vì `sc_id` = `{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) (mỗi platform tự đánh số SC từ 1), **mỗi platform một file** để scenario platform này không đè/xoá platform khác. Lệnh luôn biết `active_platform` (từ Platform Selection / Service Detection) nên chỉ ghi đúng sổ của platform đang gen.
+Sau khi sinh tất cả file `.feature`, tạo hoặc cập nhật **sổ trace theo platform** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` cho mỗi UC — một sổ riêng cho mỗi platform (`system` / `web` / `app` / `webview` / …). Vì `sc_id` = `{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) (mỗi platform tự đánh số SC từ 1), **mỗi platform một file** để scenario platform này không đè/xoá platform khác. Lệnh luôn biết `active_platform` (từ Platform Selection / Service Detection) nên chỉ ghi đúng sổ của platform đang gen.
 
 > **Umbrella + `spec_source`:** cả file `.feature` **và** trace `.tsv` đều ghi vào **spec repo** (`{spec_source}/specs/{domain}/{prd-slug}/bdd/…` và `{spec_source}/.trace/{domain}/{prd-slug}/…`, do context-loader phân giải) — một thao tác ghi **single-repo**, commit/push vào spec submodule. (Trace được gộp trong spec repo để PM quản lý mọi status ở một chỗ; các lệnh phía code cập nhật liên-repo sau.)
 

package/core/commands/generate-code.md

@@ -266,7 +266,7 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 
 ## Phase Detection
 
-> **Nguồn chuẩn quyết BE/FE = `@trace.platform` của FILE FEATURE** (`system` → BE · `web`/`app` → FE). KHÔNG dùng `platform_type` (suy từ module) để quyết BE/FE — nó chỉ dùng cho **idiom stack/module** (cú pháp, layer, thư viện). Lý do: repo fullstack một-module (vd Next.js có API route) có `platform_type` cố định một giá trị, nhưng vẫn có cả feature `system` (BE) lẫn `web` (FE) — chỉ tag của chính feature mới đúng.
+> **Nguồn chuẩn quyết BE/FE = `@trace.platform` của FILE FEATURE** — **`system` → BE · MỌI platform khác → FE** (`web`, `app`, `webview`, và bất kỳ surface nào project khai thêm). Luật viết bằng **phủ định**, không phải liệt kê: liệt kê `web`/`app` làm platform thứ tư không khớp nhánh nào, và lệnh sẽ phải tự đoán — sinh sai loại code mà không cờ nào báo. KHÔNG dùng `platform_type` (suy từ module) để quyết BE/FE — nó chỉ dùng cho **idiom stack/module** (cú pháp, layer, thư viện). Lý do: repo fullstack một-module (vd Next.js có API route) có `platform_type` cố định một giá trị, nhưng vẫn có cả feature `system` (BE) lẫn `web` (FE) — chỉ tag của chính feature mới đúng.
 
 Parse `$ARGUMENTS` tìm flag `--phase` và `--force`:
 
@@ -275,7 +275,7 @@ Parse `$ARGUMENTS` tìm flag `--phase` và `--force`:
 | `--phase=ui` | FE Phase 1 — sinh UI + layer mock API từ System BDD contract |
 | `--phase=integration` | FE Phase 2 — thay mock adapter bằng lời gọi API thật từ tech docs |
 | `--force` | "Gen lại tường minh" — **CHỈ** bỏ qua guard status ở §Read Trace State (không skip row đang `OK`). Xem định nghĩa hẹp bên dưới. |
-| *(không có)* | Default — full: **BE/`system`** → full backend; **FE (`web`/`app`)** → **FE full** (sinh UI + wire API thật trong một lần, không qua bước mock) |
+| *(không có)* | Default — full: **`system`** → full backend; **mọi platform khác** (`web`/`app`/`webview`/…) → **FE full** (sinh UI + wire API thật trong một lần, không qua bước mock) |
 
 > **`--force` có phạm vi HẸP — đây là ranh giới cứng, không phải khuyến nghị.**
 > Nó bỏ qua **đúng một** thứ: luật "row `OK` thì skip" ở §Read Trace State. **Mọi guard khác giữ nguyên hiệu lực:** Scope Lock (cấm implement scenario của `.feature` khác) · quy tắc EXTEND phi-phá-huỷ (đọc lại trước khi ghi · CẤM full Write trên file đã tồn tại · output phải là superset chặt) · Guard sau-ghi · Fill-before-create · Build Verify.

package/core/commands/generate-tech-docs.md

@@ -421,7 +421,7 @@ Ghi/mở rộng `{output_path}` dùng template dưới đây, chỉ sinh **nội
 @trace.ucs: {TICKET-ID}-UC1, {TICKET-ID}-UC2{, …}
 @trace.service: {service — từ header BDD @trace.service}
 @trace.module: {module liên quan — vd dotnet, angular}
-@trace.platforms: {system | web | app — tuỳ thư mục BDD nào tồn tại}
+@trace.platforms: {system | web | app | webview | … — tuỳ thư mục BDD nào tồn tại}
 @trace.bdd_versions: {MAP theo từng platform — số nhiều, KHÁC @trace.bdd_version (scalar) của .feature — vd system=1.5, web=1.9, app=1.7; chỉ platform có mặt. Mỗi feature mang bdd_version riêng; đừng gộp về một số.}
 @trace.api_source: {existing | —}
 @trace.revision: 1
@@ -794,7 +794,7 @@ sequenceDiagram
 
 | UC | Feature | Platforms | Section phủ | Trạng thái |
 |----|---------|-----------|------------------|--------|
-| {TICKET-ID}-UC1 | {title} | {system, web, app} | §… | ✅ Covered |
+| {TICKET-ID}-UC1 | {title} | {system, web, app, webview…} | §… | ✅ Covered |
 
 ### Độ phủ Scenario UC1
 

package/core/commands/map-testids.md

@@ -180,7 +180,7 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 Phân giải `platform` từ `@trace.platform` / `platform_type`. Test-id là chuyện của **FE/App** — nếu `system` / backend → HALT:
 ```
-❌ /map-testids chỉ áp dụng cho FE/App (web/app). BE không có UI test-id.
+❌ /map-testids chỉ áp dụng cho platform CLIENT (mọi platform trừ `system` — web/app/webview/…). BE không có UI test-id.
 ```
 Phân giải attribute test-id từ `@trace.testid_attr` (hoặc theo module): web `data-testid` · React Native `testID` · Flutter `Key`/`Semantics(identifier:)` · native iOS `accessibilityIdentifier`.
 

package/core/commands/validate-traces.md

@@ -828,7 +828,7 @@ Schema:
       }
     },
     "by_platform": {
-      "<web | app | system — CHỈ platform thực sự có scenario>": {
+      "<platform — web | app | system | webview | … ; CHỈ platform thực sự có scenario>": {
         "total_scs": 0, "coded_scs": 0, "tested_scs": 0, "drift_count": 0
       }
     }
@@ -850,7 +850,7 @@ Schema:
           "scenarios": [
             {
               "sc_id": "<e.g. PAY-UC01-SC1>",
-              "platform": "web | app | system",
+              "platform": "web | app | system | webview | …",
               "sc_title": "<title>",
               "spec_ver": "<current version from .feature>",
               "gen_ver": "<version at codegen time>",
@@ -956,7 +956,7 @@ Schema:
     "bdd_drift": [
       {
         "uc_id": "<UC-ID>",
-        "platform": "web | app | system",
+        "platform": "web | app | system | webview | …",
         "code_bdd_version": "<@trace.bdd_version trong code>",
         "current_bdd_version": "<@trace.bdd_version của .feature>",
         "drifted_scs": ["<SC đang DRIFT của UC này>"],
@@ -966,7 +966,7 @@ Schema:
     "techdoc_stale_vs_bdd": [
       {
         "uc_id": "<UC-ID>",
-        "platform": "web | app | system",
+        "platform": "web | app | system | webview | …",
         "techdoc_bdd_version": "<entry trong map @trace.bdd_version của tech-doc>",
         "current_bdd_version": "<@trace.bdd_version của .feature>",
         "fix": "/generate-tech-docs <feature-file> then /review-tech-docs"
@@ -993,7 +993,7 @@ Schema:
     "orphaned": [
       {
         "sc_id": "<SC-ID đã bị xoá khỏi .feature>",
-        "platform": "web | app | system",
+        "platform": "web | app | system | webview | …",
         "implemented_by": "<ClassName.method còn tồn tại>",
         "test_classes": ["<test còn trỏ vào SC này>"],
         "fix": "xoá code + test, HOẶC đưa scenario trở lại .feature"
@@ -1037,7 +1037,7 @@ Schema:
     "service_unrouted": [
       {
         "sc_id": "<SC-ID>",
-        "platform": "web | app | system",
+        "platform": "web | app | system | webview | …",
         "domain": "<domain của PRD>",
         "value": "unrouted | unresolved",
         "reason": "<lý do context-loader đã ghi — vd: domain chưa có entry trong services:>",

package/core/steps/context-loader.md

@@ -403,7 +403,7 @@ Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
 Lessons   : {loaded — {n} active cho lệnh này ({tổng} tổng) | chưa có}
             {⚠️ CHỈ IN khi tổng ≥ 40: "{tổng} guardrail đang hoạt động — /learn --review để rà"}
-Platform  : {active_platform: system | web | app | — nếu chưa xác định}
+Platform  : {active_platform: system | web | app | webview | … | — nếu chưa xác định}
 Service   : {active_service} ({active_service_module}) [← domain{/platform}{/prd_slug} nếu route qua by_prd_slug] | multi (map-theo-platform hoặc map-theo-prd_slug, chốt khi target đủ platform/prd_slug) | single-service
 Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
 Status    : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL}

package/core/templates/ci/trace-gate.gitlab-ci.yml

@@ -0,0 +1,169 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# SDD Framework — Trace Gate (GitLab CI)
+#
+# COPY nội dung này vào `.gitlab-ci.yml` ở gốc repo. Nó KHÔNG tự chạy từ
+# `.agent/templates/` — mọi thứ trong `.agent/` là bản sinh ra, bị ghi đè mỗi lần
+# `/update-framework`.
+#
+# ⚠️ Repo chưa có `.gitlab-ci.yml`? Thêm file này = mọi push/MR từ nay sẽ kích hoạt
+#    pipeline. Đó là mục đích — nhưng hãy biết trước.
+#
+# GIỚI HẠN — đọc trước khi tin:
+#   Job này chứng minh "report khớp SỔ, và sổ không có cờ 🔴".
+#   Nó KHÔNG chứng minh "sổ khớp CODE" — việc đó cần quét tag trong source, đọc
+#   .feature, so version, tức cần `/validate-traces` (một lệnh LLM, không chạy được
+#   trong CI thường). Nên nó bắt ca phổ biến "quên chạy lại /validate-traces",
+#   nhưng KHÔNG bắt ca "sửa code mà không đụng sổ".
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# BỐN BẪY KHI DỊCH TỪ GITHUB ACTIONS — file này đã vá cả bốn.
+#
+# Bản GitHub (`trace-gate.yml`) dựa vào ba thứ `ubuntu-latest` cho sẵn mà GitLab
+# KHÔNG có. Hai bẫy đầu ỒN (job đỏ, thấy ngay). Hai bẫy sau IM LẶNG — job XANH
+# trên một phép kiểm chưa bao giờ chạy, tức đúng thứ cổng này tồn tại để chống.
+#
+#   1. ỒN     thiếu `tags:`        → job stuck "no active runners that can run this job",
+#                                    dù runner Online. Group/shared runner thường có
+#                                    `run_untagged = false`, nên job KHÔNG tag sẽ không
+#                                    bao giờ được nhận. Điền đúng tag của runner bạn.
+#   2. ỒN     thiếu Node           → `npx: not found`. GitHub có bước
+#                                    `actions/setup-node@v4`; GitLab không có tương
+#                                    đương, và bước đó là chỗ cấp `npx`.
+#   3. IM LẶNG thiếu `GIT_DEPTH: 0` → GitLab clone SHALLOW (mặc định 20). `git diff
+#                                    BASE...HEAD` không có merge-base ⇒ ra RỖNG ⇒ job
+#                                    `require-fresh-audit` in "MR không chạm tag nào"
+#                                    và PASS, trong khi bạn vừa đổi tag. XANH GIẢ.
+#   4. IM LẶNG image không có git   → `node:20-alpine` và `node:20-slim` đều KHÔNG có
+#                                    git. Mà lint-trace cần git cho T10 (luật merge) và
+#                                    T11 (bị gitignore) — hai điều kiện `gate-trace` G0
+#                                    NÂNG thành chặn. Không hỏi được git thì (trước T13)
+#                                    G0 in "✅ sổ được bảo vệ — 2/2 điều kiện": một lời
+#                                    KHẲNG ĐỊNH trên bằng chứng chưa bao giờ được thu.
+#                                    Từ v0.7.2 lint phát **T13** và gate FAIL đúng ca đó
+#                                    — nhưng cách sửa vẫn là dùng image CÓ git.
+#
+# `before_script` dưới đây in `node -v` và `git --version` để bẫy 2 và 4 lộ ra ở
+# dòng log đầu tiên, thay vì lộ ra dưới dạng một dấu xanh sai.
+# ─────────────────────────────────────────────────────────────────────────────
+
+stages:
+  - trace
+
+variables:
+  # ── BẪY 3 ── BẮT BUỘC. Không có dòng này thì `require-fresh-audit` XANH GIẢ.
+  GIT_DEPTH: 0
+
+  # PIN VERSION, đừng `@latest`. Cổng này quyết định PR nào được merge — một bản
+  # release framework đổi hành vi cổng giữa sprint là thứ bạn muốn tự chọn thời điểm.
+  SDD_VERSION: "0.7.2"
+
+  # Sổ/spec nằm trong submodule (umbrella + spec_source)? Bỏ comment dòng dưới.
+  # Không có nó, lint thấy 0 sổ → gate FAIL ở G2 ("chưa audit ≠ sạch"). Ồn, không im.
+  # GIT_SUBMODULE_STRATEGY: recursive
+
+.sdd:
+  # ── BẪY 2 + 4 ── `node:20` là bản Debian: có SẴN cả node lẫn git.
+  # KHÔNG dùng `node:20-alpine` / `node:20-slim` — chúng thiếu git (xem bẫy 4).
+  # Buộc phải dùng alpine? Thêm: `- apk add --no-cache git`
+  image: node:20
+
+  # ── BẪY 1 ── ĐỔI thành đúng tag của runner bạn. Kiểm ở Settings → CI/CD → Runners.
+  # Runner Online mà job vẫn stuck ⇒ hoặc lệch tag, hoặc runner không bật
+  # "Run untagged jobs", hoặc runner chỉ nhận protected ref (MR pipeline chạy trên
+  # `refs/merge-requests/N/head` — KHÔNG phải protected ref, kể cả khi đích là main).
+  tags:
+    - CHANGE_ME
+
+  before_script:
+    # Hai dòng này tồn tại để bẫy 2 và 4 lộ ra NGAY, chứ không lộ ra dưới dạng dấu xanh sai.
+    - node -v
+    - git --version
+
+# ── 1+2. Cấu trúc sổ + cổng chặn cờ 🔴 ───────────────────────────────────────
+# Sổ trace 24 cột do LLM ghi tay: một dấu tab thiếu dồn mọi ô sang trái, ô `status`
+# nhận một ngày tháng, và không cờ nào bật. lint bắt việc đó (T1/T2/T3), bắt marker
+# conflict git lọt vào sổ (T7), sổ thiếu luật merge (T10), sổ bị gitignore (T11),
+# row vừa DRIFT vừa mang `pass` (T12), và ca không hỏi được git (T13).
+#
+# `--gate-trace` tự chạy lại lint ở tầng G1, nên bước lint riêng ở trên là để có log
+# dễ đọc khi đỏ. Muốn gọn thì bỏ nó và chỉ giữ `--gate-trace`.
+trace-gate:
+  extends: .sdd
+  stage: trace
+  script:
+    - npx -y @educa-corp/sdd-framework@${SDD_VERSION} --lint-trace
+    - npx -y @educa-corp/sdd-framework@${SDD_VERSION} --gate-trace
+  artifacts:
+    when: always
+    paths:
+      - .trace/trace-report.json
+    expire_in: 1 week
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+# ── 3. Ép audit phải TƯƠI khi thứ report đang KHẲNG ĐỊNH bị đổi ──────────────
+# ĐO BẰNG TAG, KHÔNG BẰNG `src/**`: framework có luật boundary-only tagging, nên
+# "MR có sửa src/ không?" chặn oan cả MR chỉ thêm một field vào DTO — một file không
+# mang lời khẳng định trace nào. Cái gì báo oan thì bị tắt, rồi mất luôn phần cần chặn.
+# Câu hỏi đúng: "MR có chạm dòng nào mang tag mà report đang khẳng định không?"
+#   sửa log trong Controller  → cho qua
+#   thêm field vào DTO        → cho qua
+#   thêm method + @implements → CHẶN
+#   lấp một @trace.stub       → CHẶN
+#
+# 7 tag dưới đây khai ở `bin/trace-schema.json` → `gate.audit_invalidating_tags`;
+# `self-check` R10 canh danh sách này khớp schema. Tag đổi tên mà file CI không biết
+# ⇒ grep không khớp gì ⇒ job LUÔN XANH ⇒ cổng mù trong im lặng.
+#
+# GIỚI HẠN ĐÃ BIẾT: đổi tên class (AuthService → AuthenticationService) không chạm
+# dòng tag ⇒ job này bỏ lọt, dù cột `implemented_by` giờ trỏ vào tên không còn. Chấp
+# nhận có chủ ý: ca đó ít gặp và KHÔNG im lặng (lần `/validate-traces` sau báo ngay),
+# còn báo oan thì xảy ra mỗi ngày và hậu quả là CỔNG BỊ TẮT.
+require-fresh-audit:
+  extends: .sdd
+  stage: trace
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - |
+      # ── BẪY 3, phần thứ hai ── GitHub có `github.base_ref` sẵn trong checkout.
+      # GitLab phải FETCH branch đích TRƯỚC — nếu không thì "$BASE" không tồn tại,
+      # `git diff` ra rỗng, và job PASS sai. Refspec tường minh để chắc chắn
+      # `refs/remotes/origin/<branch>` được cập nhật.
+      BR="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+      git fetch --no-tags origin "+refs/heads/${BR}:refs/remotes/origin/${BR}"
+      BASE="origin/${BR}"
+
+      # Fail-fast: chứng minh merge-base tồn tại. Không có nó, mọi kết luận bên dưới
+      # dựa trên một diff rỗng — và "rỗng" ở đây nghĩa là "không biết", không phải "sạch".
+      if ! git merge-base "$BASE" HEAD >/dev/null 2>&1; then
+        echo "🔴 Không tìm được merge-base giữa $BASE và HEAD."
+        echo "   Gần như chắc chắn là clone SHALLOW — kiểm biến GIT_DEPTH: 0 ở đầu file."
+        echo "   Không có merge-base thì git diff ra rỗng và job này sẽ PASS SAI."
+        exit 1
+      fi
+
+      TAGS='@trace\.(implements|verifies|seam_port|seam_pending|stub|stub_owner|stub_for)'
+      touched=$(git diff -U0 "$BASE"...HEAD | grep -E "^[+-].*${TAGS}" | head -5 || true)
+      audit=$(git diff --name-only "$BASE"...HEAD | grep -E 'trace-report\.json$' | head -1 || true)
+
+      if [ -n "$touched" ] && [ -z "$audit" ]; then
+        echo "🔴 MR đổi tag trace nhưng không kèm trace-report.json được sinh lại."
+        echo ""
+        echo "Những dòng này đã đổi:"
+        echo "$touched" | sed 's/^/    /'
+        echo ""
+        echo "Trace gate chỉ chứng minh 'report khớp SỔ'. Tag vừa đổi mà chưa audit lại"
+        echo "thì mọi cờ 🔴 trong report nói về trạng thái TRƯỚC khi bạn sửa."
+        echo ""
+        echo "Chạy trong Claude Code:  /validate-traces"
+        echo "Rồi commit:              .trace/trace-report.json + *.tsv"
+        exit 1
+      fi
+
+      if [ -n "$touched" ]; then
+        echo "✅ Tag trace có đổi, và audit đã được sinh lại cùng MR."
+      else
+        echo "✅ MR không chạm tag nào mà report đang khẳng định — audit vẫn còn đúng."
+      fi

package/core/templates/project-context.yaml

@@ -26,7 +26,7 @@ project:
 paths:
   # Feature-Package Layout:
   #   specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md      — PRD document
-  #   specs/{domain}/{prd-slug}/bdd/{platform}/                — BDD .feature  ({platform} = web | app | system)
+  #   specs/{domain}/{prd-slug}/bdd/{platform}/                — BDD .feature  ({platform} = web | app | system | webview)
   #   specs/{domain}/{prd-slug}/tech-docs/                     — Technical design (ONE merged doc per PRD: {TICKET-ID}-tech-design.md)
   #   specs/{domain}/{prd-slug}/design-spec/                   — Design specs (FE/App only)
   #   specs/{domain}/{prd-slug}/changelog/                     — PRD changelog overflow (created once history exceeds 5 versions)
@@ -97,7 +97,7 @@ paths:
   # {spec_source}/specs so FE/App read the contract via the spec submodule.
   tech_docs_dir: "specs"
 
-  # Design Specs (FE/App platforms only — web, app).
+  # Design Specs (client platforms only — every platform except `system`: web, app, webview).
   # In the feature-package layout, design-specs live at specs/{domain}/{prd-slug}/design-spec/.
   # This variable is no longer needed as a separate path — derived from specs_dir.
   # design_spec_dir: "specs/design-spec"   ← removed; use specs_dir instead
@@ -163,7 +163,7 @@ domains:
 #   #
 #   # FORM B — PER-PLATFORM MAP (one business-domain implemented on several platforms /
 #   #          submodules — a merged monorepo/workspace). No direct `path`; instead one
-#   #          sub-key per platform (system | web | app). context-loader routes by the
+#   #          sub-key per platform (system | web | app | webview). context-loader routes by the
 #   #          target .feature's @trace.platform → picks {path, module} for that platform.
 #   #          The PRD keeps a SINGLE business @trace.domain (do NOT invent onboarding-web).
 #   {{DOMAIN_2}}:

package/core/templates/tech-design.template.md

@@ -39,7 +39,7 @@
 @trace.ucs: {TICKET-ID}-UC1, {TICKET-ID}-UC2{, …}
 @trace.service: {service — từ header BDD @trace.service}
 @trace.module: {module liên quan — vd dotnet, angular}
-@trace.platforms: {system | web | app — tuỳ thư mục BDD nào tồn tại}
+@trace.platforms: {system | web | app | webview | … — tuỳ thư mục BDD nào tồn tại}
 @trace.bdd_versions: {MAP theo từng platform — số nhiều, KHÁC @trace.bdd_version (scalar) của .feature — vd system=1.5, web=1.9, app=1.7; chỉ platform có mặt. Mỗi feature mang bdd_version riêng; đừng gộp về một số.}
 @trace.api_source: {existing | —}
 @trace.revision: 1
@@ -412,7 +412,7 @@ sequenceDiagram
 
 | UC | Feature | Platforms | Section phủ | Trạng thái |
 |----|---------|-----------|------------------|--------|
-| {TICKET-ID}-UC1 | {title} | {system, web, app} | §… | ✅ Covered |
+| {TICKET-ID}-UC1 | {title} | {system, web, app, webview…} | §… | ✅ Covered |
 
 ### Độ phủ Scenario UC1
 

package/docs/02-concepts/architecture.md

@@ -66,7 +66,7 @@ Spec-driven thành/bại phụ thuộc **~80%** vào việc context được n
                      bin/self-check.js (fail build)      --init cài vào đây
 ```
 
-**Vì sao slim (G45):** build inline `{{include:}}` vào **từng** file lệnh. Với 32 lệnh, kết quả là
+**Vì sao slim (G45):** build inline `{{include:}}` vào **từng** file lệnh. Đo lúc đó (32 lệnh), kết quả là
 2069 KB mà chỉ 580 KB là nội dung riêng của chúng — **72% là vài step giống hệt nhau, chép 30 lần**.
 `/generate-code` từng nặng 108 KB (≈27k token đọc **trước** khi làm gì), gần một nửa không nói gì về
 việc sinh code. Cái giá thật không phải tiền: trên PRD nhiều UC nó làm tăng rủi ro **cạn context

package/docs/02-concepts/overview.md

@@ -11,7 +11,7 @@
 ```mermaid
 flowchart TD
     S["0 · Setup<br/>/setup-ai-first"] --> D["1 · Discovery<br/>/define-product"]
-    D --> SP["2 · Specification<br/>/generate-prd · /refine-prd · /review-context"]
+    D --> SP["2 · Specification<br/>/generate-prd · /extend-prd · /amend-prd<br/>/refine-prd · /review-context"]
     SP --> DS["3 · Design-Spec<br/>(chỉ FE/App)"]
     SP --> B["4 · BDD<br/>/generate-bdd · /review-context"]
     DS --> B