@educa-corp/sdd-framework 0.7.0 → 0.7.1

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)."
@@ -1614,8 +1640,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.1

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/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

package/docs/02-concepts/pipeline-steps/02-specification.md

@@ -3,15 +3,20 @@
 # Bước 2 · Specification — Hình thành đặc tả (PRD)
 
 > **Tóm tắt.** Biến khung intent thành **PRD** chuẩn nghiệp vụ, tinh chỉnh qua 3 lăng kính, rồi qua **gate chất lượng** để PO đóng dấu `approved`.
-> **Commands:** `/generate-prd` (lần đầu) · `/extend-prd` (thêm vào PRD đã có) → `/refine-prd` → `/review-context`
+> **Commands:** `/generate-prd` (lần đầu) · `/extend-prd` (**thêm** vào PRD đã có) · `/amend-prd` (**đổi** yêu cầu đã có) → `/refine-prd` → `/review-context`
 
-> **Chọn lệnh nào — PRD mới vs PRD đã có:**
+> **Chọn lệnh nào — bốn nhánh, phân biệt bằng THAO TÁC GHI:**
 >
-> | Tình huống | Lệnh | Vì sao không dùng cái kia |
-> |---|---|---|
-> | PRD **chưa tồn tại** | `/generate-prd` | — |
-> | PRD đã có, **thêm** UC/AC/BR mới | **`/extend-prd`** | `/generate-prd` **từ chối chạy** trên file đã có |
-> | PRD đã có, **sửa vấn đề** đã soi ra | `/refine-prd` → Review Board → `--resume` | `/refine-prd` **không thêm được** yêu cầu mới — nó tự cấm đụng section ngoài findings |
+> | Tình huống | Lệnh | Ghi kiểu gì | Vì sao không dùng cái kia |
+> |---|---|---|---|
+> | PRD **chưa tồn tại** | `/generate-prd` | **Write** cả file | — |
+> | PRD đã có, **THÊM** UC/AC/BR mới | **`/extend-prd`** | Edit **add-only** — output là **superset chặt** | `/generate-prd` **từ chối chạy** trên file đã có |
+> | PRD đã có, **ĐỔI** một yêu cầu đang đúng cú pháp | **`/amend-prd`** | Edit **tại chỗ** — output **KHÔNG** phải superset | `/extend-prd` chỉ add-only; `/refine-prd` chỉ áp finding của chính nó |
+> | PRD đã có, sửa **vấn đề review đã soi ra** | `/refine-prd` → Review Board → `--resume` | Edit trong phạm vi finding | `/refine-prd` **không thêm/đổi được** theo ý định mới — nó tự cấm đụng section ngoài findings |
+>
+> **Xoá hẳn một BR/AC → không có lệnh, và có chủ ý:** xoá row làm `@trace.business_rules` trong `.feature` trỏ vào ID không còn ⇒ `TRACE_ORPHAN` 🔴. Dùng `/amend-prd --retire {ID}` — khai tử **tại chỗ**, giữ nguyên row + ID.
+>
+> ⚠️ **Sửa tay file `.md` là điểm mù (GAPS-v4 G54).** Mọi drift detector so **nhãn version**, không so nội dung (0 content hash trong codebase) — sửa mà không bump version ⇒ **0 cờ**. `/validate-traces` Step 3.9 canh cửa sau bằng cờ 🔴 `PRD_UNTRACKED_EDIT`.
 >
 > **`/generate-prd` dừng hẳn (không hỏi Y/N) nếu file đã tồn tại.** Ghi đè sẽ mất `# Change Log` + rollover, Version/Status thật, và **đánh số lại BR từ đầu** — cái cuối lan **ra ngoài file**, phá mọi `@trace.business_rules` trong `bdd/` đã sinh. Ba mất mát đều không hoàn tác được từ trong lệnh, nên không đặt sau một phím bấm.
 
@@ -41,6 +46,7 @@ PRD là **hợp đồng nghiệp vụ** giữa PO ↔ Dev ↔ AI. Đây là **c
 |------|---------|---------|
 | `/generate-prd` | **Sinh** PRD draft từ product-definition. Từ chối chạy nếu PRD đã tồn tại | PRD `Status: draft` |
 | `/extend-prd` | **Thêm** UC/AC/BR vào PRD đã duyệt — đánh số **nối tiếp**, ghi **add-only** + guard sau-ghi, drain `feedback/prd-change-requests/` | PRD v+1, `Status → draft` |
+| `/amend-prd` | **Đổi tại chỗ** một AC/BR/UC đã duyệt — PO khai tường minh `amend_targets`, kiểm va chạm, guard sau-ghi **HAI CHIỀU** (Bảo toàn + Giới hạn). `--retire {ID}` khai tử tại chỗ | PRD v+1, `Status → draft` |
 | `/refine-prd` | **Tinh chỉnh** qua 3 lăng kính DEV/SA/PO (fan-out per-UC) | Findings để PO accept/reject |
 | `/review-context` | **Gate chất lượng** — findings P0–P5, phải sạch critical | PO đặt `Status: approved` |
 

package/docs/02-concepts/pipeline-steps/07-dev-selftest.md

@@ -24,6 +24,8 @@ Trước khi đẩy sang QC chính thức, Dev cần một vòng **kiểm nhanh
 - Cho phép **thử tại chỗ** trên service/app đang chạy (`/dev-smoke-test`).
 
 > **`dev_selftest` ≠ `qc_status`.** Hai trục **độc lập**: dev smoke (nhanh, tự kiểm) vs QC chính thức (Playwright, evidence). Không lấn quyền nhau.
+>
+> ⚠️ **Nhưng "độc lập" chỉ đúng với `status` về KẾT QUẢ CHẠY, không đúng về QUYỀN KHẲNG ĐỊNH** *(GAPS-v4 G55)*. `pass` mang nghĩa *"scenario này đã được nghiệm thu theo spec **hiện tại**"* — nên trên row `DRIFT`/`ORPHANED`, `/dev-run-test` và `/qc-run-test` **không được** ghi `pass`; chúng hạ về `not_run`. `fail`/`skip` thì ghi bình thường. `lint-trace` **T12** bắt trạng thái `DRIFT + pass` ở sổ thật, bất kể ai ghi ra.
 
 ---
 

package/docs/02-concepts/pipeline-steps/08-qc-automation.md

@@ -21,6 +21,7 @@
 
 - Phân rã yêu cầu thành test case bám scenario, phát hiện **gap tài liệu**.
 - Chạy test thật, ghi **`qc_status` chính thức** + **evidence**.
+  ⚠️ Nhưng `/qc-run-test` **đọc cột `status` trước khi ghi `pass`** *(GAPS-v4 G55)*: row `DRIFT`/`ORPHANED` + test xanh → hạ về `not_run`, và **không** đóng bug nào ở lần chạy đó. `fail`/`skip` ghi bình thường.
 - Phân loại FAIL: **script-bug** (sửa script) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
 - Đẩy **product-gap** ngược về PO/Dev.
 

package/docs/02-concepts/pipeline-steps/09-validate-traces.md

@@ -2,7 +2,8 @@
 
 # Bước 9 · Validate Traces — Ma trận độ phủ (Coverage Matrix)
 
-> **Tóm tắt.** Check độ phủ giữa **spec ↔ code ↔ test** — 2 chiều quét, **6 tầng drift**, 4 cờ 🔴 chặn PR, 2 cờ ⓘ. Chỉ ra chỗ chưa phủ — mặc định **không sửa gì**.
+> **Tóm tắt.** Check độ phủ giữa **spec ↔ code ↔ test** — 2 chiều quét, **6 tầng drift**, 4 cờ 🔴 chặn PR, 1 cờ 🔴 không-chặn (`PRD_UNTRACKED_EDIT`), 2 cờ ⓘ. Chỉ ra chỗ chưa phủ — mặc định **không sửa gì**.
+> **Có phạm vi:** `--domain {d}` · `--prd {TICKET-ID}` · `--uc {UC-ID}`; không cờ nào = toàn bộ.
 > **Command:** `/validate-traces` · `--realign-prd-version {UC-ID}` · `--realign-techdoc-revision {UC-ID}`
 >
 > *Lệnh **read-only** ở chế độ thường. Hai flag `--realign-*` là ngoại lệ có kiểm soát: chúng sửa **đúng dòng `@trace.*`** trong code, không đụng logic — xem [Realign](#realign--đường-ra-cho-cờ-ⓘ).*
@@ -41,7 +42,7 @@ Traceability chỉ có giá trị khi **kiểm được**. Bước này cho mộ
 | Ma trận coverage spec ↔ code ↔ test | Trạng thái từng SC + `code_coverage` tổng |
 | `{trace_dir}/trace-report.json` | Bản máy đọc cho **panel VS Code** ("Spec Driven Docs Tools") — bị **ghi đè** mỗi lần chạy |
 | `{trace_dir}/trace-history.jsonl` | **Nhật ký append-only** — mỗi lần chạy ghi thêm 1 dòng *delta*. Đây là **dữ liệu**, không phải mirror: **phải commit**, mất là mất vĩnh viễn |
-| Cờ audit | 6 cờ drift + 4 cờ 🔴 chặn PR + 2 cờ ⓘ (bảng dưới) |
+| Cờ audit | 6 cờ drift + 4 cờ 🔴 chặn PR + `PRD_UNTRACKED_EDIT` 🔴 (không chặn) + 2 cờ ⓘ (bảng dưới) |
 | Hàng đợi | Đếm PRD change request còn `Open` kèm **số ngày chờ** (Step 7b) |
 
 ---
@@ -68,6 +69,25 @@ Traceability chỉ có giá trị khi **kiểm được**. Bước này cho mộ
 
 ## Framework xử lý thế nào (Mechanics)
 
+### Phạm vi audit — `--domain` / `--prd` / `--uc`
+
+Đây là **lệnh đắt nhất** trong framework: ~24k token chỉ dẫn + ~9k `context-loader`, rồi đọc **mọi** PRD · `.feature` · tech-doc · design-spec · file source có tag · `.tsv`. Chi phí tăng **tuyến tính theo cả repo**, không theo phần việc đang làm.
+
+| Cờ | `scope.kind` | Phạm vi |
+|---|---|---|
+| *(không có)* | `all` | Toàn bộ |
+| `--domain {d}` | `domain` | Một domain |
+| `--prd {TICKET-ID}` | `prd` | Một feature-package |
+| `--uc {UC-ID}` | `uc` | Một UC — **mọi platform của nó** |
+
+**`/sync` Step 1e nói cho bạn biết scope là gì**: nó liệt kê PRD nào vừa đổi *(so với lần pull)* và PRD nào đã đổi *kể từ lần audit gần nhất* — con số thứ hai tích luỹ đúng qua nhiều lần pull. Hai lệnh khớp nhau thành một vòng: `/sync` chỉ chỗ → audit scoped rẻ → sửa → audit **toàn bộ** một lần trước khi tạo PR.
+
+⚠️ **Biên bản có scope KHÔNG BAO GIỜ được coi là đầy đủ.** Report mang field `scope`, và `gate-trace` **G2 fail** nếu `scope.kind !== "all"` — **không ngoại lệ**, không đếm xem trên đĩa có bao nhiêu domain. Muốn tạo PR thì phải có một lần audit **toàn bộ** đã commit.
+
+> **Vì sao điều kiện phải tuyệt đối (GAPS-v4 G57):** bản cũ hỏi *"còn domain **nào khác** không"*, nên trong repo **một domain** thì không còn domain nào khác ⇒ **không fail** ⇒ một biên bản hẹp-theo-PRD được nhận là *"toàn bộ"*. Thêm cờ scope mà không siết G2 là **tự tay mở** đúng cái *"cấp giấy xanh cho thứ chưa ai xem"* mà chú thích của gate cảnh báo.
+
+**Ba chỗ cố ý KHÔNG âm thầm:** `--prd`/`--uc` không phân giải được → **DỪNG** *(không rơi về `all` — chạy toàn bộ khi người ta xin một phần là đốt 30 phút; và không audit rỗng rồi báo "sạch" trên 0 row)* · nhiều cờ scope cùng lúc → **DỪNG** *(không tự ưu tiên)* · **lint vẫn chạy toàn bộ** dù audit có scope *(sổ hỏng ở domain khác vẫn là sổ hỏng, và lint rẻ vì không cần LLM)*.
+
 ### Phân loại `status` từng SC (thứ tự ưu tiên, rule sớm thắng)
 
 | # | Trạng thái | Điều kiện |
@@ -97,6 +117,7 @@ Chiều ngược là cần thiết vì gen lại BDD có thể làm một SC bi
 
 | Cờ | So cái gì | Step |
 |---|---|:---:|
+| `PRD_UNTRACKED_EDIT` 🔴 | **Nội dung PRD đổi mà nhãn `Version` KHÔNG đổi** — `git diff` **và** `git status` so với mốc `spec_baseline` của lần audit trước. Có người sửa ngoài đường chính thức | **3.9** |
 | `PRD_DRIFT` | Version PRD vs cột `prd_version` vs `@trace.prd_version` trong code — **và** changelog **có** nêu UC này | 4 |
 | `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` | `@trace.revision` tech-doc vs cột đã lưu — **và** changelog nêu UC này | 5 |
 | `BDD_DRIFT` | `@trace.bdd_version` trong code vs `.feature` hiện tại | 5c |
@@ -133,7 +154,17 @@ Chiều ngược là cần thiết vì gen lại BDD có thể làm một SC bi
 
 Tệ hơn: **làm theo hướng dẫn cũng không tắt được.** `/generate-bdd` sạch được cột TSV, nhưng tag trong code chỉ `/generate-code` ghi — mà nó thấy row đang `OK` là **skip**. Vòng lặp đóng, và lối ra duy nhất là ép sinh lại code cho hàng loạt UC không hề thay đổi.
 
-Bộ lọc đọc **scope của row changelog** (`/refine-prd` Phase 3 và `/extend-prd` bắt buộc ghi UC/AC/BR bị ảnh hưởng — `/generate-bdd` Version Check đã dùng dữ liệu này từ trước). **Row nào mơ hồ → gắn 🟠 cho MỌI UC** — lưới an toàn: mất tính năng *lọc*, không mất tính năng *cảnh báo*.
+Bộ lọc đọc **`{changelog_scope}` của row changelog** — một **contract máy đọc** (`bin/trace-schema.json` → `changelog_row_contract`) với **bốn** producer: `/refine-prd` Phase 3 · `/extend-prd` Bước 6 · `/amend-prd` Bước 5 · `/review-context` Fix/Resume Phase 3. `self-check` **R12** fail build nếu producer nào không có dòng template mang token.
+
+Ba bước dựng tập bị ảnh hưởng:
+
+1. **Tách mệnh đề** — ngăn bằng `;`, mỗi mệnh đề mở đầu bằng đơn vị sở hữu (`{UC-ID}:` hoặc `PRD-global:`).
+2. **Chuẩn hoá về UC** — phép phân giải **`BR/AC → UC sở hữu`**: `BR{n}` → UC có BR đó trong bảng Business Rule (PRD §3) · `AC{n}` → UC có AC đó ở dòng `**AC liên quan:**`. **Không bỏ bước này**: phép thử là *"**UC** này có trong tập?"*, nên một row chỉ nêu `sửa BR8` làm UC sở hữu BR8 rơi vào ⓘ trong khi nội dung của nó vừa đổi — và ⓘ **mở cửa** cho `--realign-prd-version` dán nhãn lại (GAPS-v4 G53).
+3. **Phân loại** *(first-match-wins)* — **row mơ hồ xét TRƯỚC**: nó là điều kiện **cấp row**, nên xét sau thì một UC có thể được xếp ⓘ trước khi ta biết là không suy đoán được gì.
+
+**Row nào mơ hồ → 🟠 cho MỌI UC** — lưới an toàn: mất tính năng *lọc*, không mất tính năng *cảnh báo*. ⚠️ Nhưng nó **không phải cái cớ để producer ghi bừa**: đúng khi **thiếu** thông tin, sai khi producer **có** thông tin mà không ghi.
+
+Mệnh đề mang hậu tố **`[no-behavior]`** → UC nêu trong đó ở lại ⓘ. Chỉ producer **chứng minh được** tính trung tính mới được dùng (`changelog_row_contract.neutral_checks`) — hiện chỉ `/review-context --fix` cho fix thuần cấu trúc (P4).
 
 > Đây là bài mà framework **đã giải đúng ở cấp scenario**: `sc_version` chỉ bump khi thân scenario thực sự đổi, vì *"bump vô cớ sẽ tạo DRIFT giả, làm cờ mất giá trị"*. Hai cờ ⓘ là bản tương ứng ở cấp tài liệu.
 

package/docs/02-concepts/pipeline-steps/10-feedback-loop.md

@@ -37,7 +37,7 @@ Framework là pipeline **một chiều** — nhưng vẫn cần đường **ph
 | `/learn` | Tất cả | Guardrail lesson | `project-lessons.md` (qua step `capture-lesson`) |
 | `/fix-bug` | Dev | Sửa lỗi có root-cause + regression test | Code + `@trace.fixes/root_cause/regression` |
 | `/extend-prd` | PO | **Drain** PRD change request → UC/AC/BR mới trong PRD | PRD v+1 · request → `archived/` |
-| `/sync` | Lead (umbrella) | Pull + submodule + **nổi feedback** + làm mới Living Docs | Chạy hằng ngày |
+| `/sync` | Lead (umbrella) | Pull + submodule + **nổi feedback** + **nổi spec delta** (Step 1e) + làm mới Living Docs | Chạy hằng ngày |
 
 ### Ba hàng đợi — mỗi cái phải có người lấy ra
 
@@ -48,6 +48,15 @@ Framework là pipeline **một chiều** — nhưng vẫn cần đường **ph
 | `prd-change-requests/` | `/propose-scenario` B | **`/extend-prd`** | `/validate-traces` Step 7b — đếm `Status: Open` kèm **số ngày chờ** |
 
 > **Vì sao cột "ai nhắc lại" quan trọng.** `/sync` chỉ hiện những gì về **trong đúng lần pull đó** (`git diff old..new`) — nó là **chuông cửa, không phải tồn kho**. Bỏ lỡ một lần là mất khỏi màn hình vĩnh viễn. Hai hàng đợi đầu không sao vì có lệnh **quét lại thư mục mỗi lần chạy**; riêng `prd-change-requests/` thì không — nên `/validate-traces` phải nhắc thay.
+
+> **Cùng nguyên tắc đó áp cho SPEC — và đó là Step 1e (GAPS-v4 G56).** Trước đó `/sync` diff đúng ba đường dẫn `feedback/*` và **bỏ qua `specs/`**, tức hỏi *"có góp ý gì mới"* rồi bỏ qua chính tài liệu mà mọi lệnh downstream đọc. Giờ nó trả lời **hai** câu bằng **hai** mốc:
+>
+> | | Mốc | Trả lời | Vấn đề nếu chỉ có nó |
+> |---|---|---|---|
+> | **1e-A** | `{old_sha}..{new_sha}` | *"đổi gì kể từ lần **PULL**"* | **chuông cửa** — reset mỗi lần pull; pull 4 ngày liền không audit thì ngày thứ 5 chỉ thấy delta của **một** ngày |
+> | **1e-B** | `spec_baseline.sha_at_audit` | *"đổi gì kể từ lần **AUDIT**"* | **tồn kho** — tích luỹ đúng |
+>
+> 1e-B đọc mốc mà `/validate-traces` Step 6b ghi (cùng khối dùng cho cờ `PRD_UNTRACKED_EDIT`). `/sync` **chỉ đọc, không bao giờ ghi** — nếu nó cũng ghi thì mốc audit trượt theo mỗi lần pull, tức 1e-B thoái hoá thành 1e-A. Và dòng `Next` giờ **rẽ nhánh theo dữ liệu**, không còn in một hằng số.
 >
 > Trước v0.4.3, hàng đợi thứ ba **không có người lấy ra**: có producer, có storage, có commit, có mặt trong `/sync` — nhưng 0 consumer, và **không gì báo**. Yêu cầu nghiệp vụ thật do tester phát hiện từ sản phẩm chạy thật rơi vào im lặng hoàn toàn. Từ v0.4.3, cả ba hàng đợi được khai vào `bin/trace-schema.json` §`queues` nên **self-check chặn build** nếu một hàng đợi mất consumer.