@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-feature-triage/workflow.md

@@ -0,0 +1,271 @@
+# NTAPP Feature Triage — Workflow
+
+Triage một feature mới **tại intake** (Stage 0.5 — trước Stage 1 Discovery), trước khi viết code/spec. Trả lời: *"Feature này nên đi lane nào, slash command kế tiếp là gì?"*
+
+Skill là **forcing function for clarity**, không phải correctness oracle. Output advisory; dev confirm bằng cách chạy command được recommend. Skill enforce hard gates (refuse nếu thiếu prerequisite), còn lại lean trên dev attestation.
+
+## Stage placement
+
+```
+(Feature intent xuất hiện)
+        │
+        ▼
+Stage 0.5: /ntapp-feature-triage
+        │
+        ├─ LANE 1 (Express hotfix preset)   → edit + SKIP_PRECOMMIT=1 + compensate 48h
+        ├─ LANE 2 (Path B quick-dev)        → /bmad-quick-dev
+        ├─ LANE 3 (Full per-slice loop)     → Stage 3-4-5 (slice active)
+        ├─ LANE 4 (Ad-hoc per-unit)         → /ntapp-feature-design (skip Stage 2b)
+        │     Trigger A: project PoC (≤3 unit toàn bộ)
+        │     Trigger B: per-feature contained (1 unit, module cũ, no contract change)
+        └─ REFUSE / ESCALATE                → unblock command cụ thể
+```
+
+---
+
+## Config resolution
+
+3-layer cascade chuẩn NTAPP:
+
+- **Layer 1** — `{project-root}/_bmad/bmm/config.yaml`: `planning_artifacts`, `stage_1_discovery`, `stage_2_architecture`, `design_system_root`.
+- **Layer 2** — `{project-root}/.bmm-config.yaml` section `ntapp-feature-triage:`: override `triage_output_dir` (default `{stage_1_discovery}/triage`), `manifest_dir` (default `{triage_output_dir}/manifests`), `scope_creep_guardrail` (default `false`).
+- **Layer 3** — Interactive fallback nếu miss.
+
+Biến runtime:
+
+| Biến | Nguồn | Dùng cho |
+|:--|:--|:--|
+| `triage_output_dir` | L1/L2/L3 | OUTPUT — `YYYY-MM-DD-{slug}.md` decision file |
+| `manifest_dir` | L1/L2/L3 | OUTPUT — `{id}.yaml` manifest (chỉ ghi khi opt-in) |
+| `scope_creep_guardrail` | L2 | Khi `true` + lane=4 trigger-B → ghi manifest |
+| `stage_2_architecture` | L1 | INPUT — `project_wbs.md`, `00_system_connectivity_integration.md`, `slices/SLICE-*.md` |
+| `stage_1_discovery` | L1 | INPUT — `epics.md` (match intent với epic) |
+| `design_system_root` | L1 | INPUT — **family root** DS (`registry.yaml` nằm ở đây khi multi-DS). Check bootstrap: Bước 0 + Bước 4.1 |
+| `ds_id_target` | derive (Bước 4.1) | DS mà feature thuộc về — resolve theo `_shared/ds-resolution.md` nhánh B |
+
+`{project-root}`: walk up từ `cwd` tìm `_bmad/` rồi `.git/`.
+
+---
+
+## Quy trình
+
+### Bước 0 — Pre-flight scan (auto, không refuse)
+
+Build state map từ filesystem:
+
+| Signal | Cách lấy |
+|:--|:--|
+| `wbs_present` | `[[ -f {stage_2_architecture}/project_wbs.md ]]` |
+| `module0_present` | `[[ -f {stage_2_architecture}/00_system_connectivity_integration.md ]]` |
+| `active_slice_count` | `ls {stage_2_architecture}/slices/SLICE-*.md 2>/dev/null \| wc -l` |
+| `ds_family_root` | `{design_system_root}` — family root. `registry.yaml` tồn tại ở đây ⇒ project multi-DS |
+| `ds_systems` | Không có `registry.yaml` → 1 system ẩn danh, root = family root (legacy). Có → parse `systems.{ds_id}`: `root`, `code_repo`, `id_prefixes`, `modules` (+ `default_ds`) |
+| `ds_bootstrap_map` | Mỗi system → `[[ -f {ds_family_root}/{root}/master_token.json ]]` (`root: "."` ⇒ chính family root). Legacy 1 system ⇒ y hệt check `{design_system_root}/master_token.json` cũ |
+| `wbs_module_list` | parse `project_wbs.md` cột "Module" — tập prefix declared |
+| `wbs_unit_count` | đếm row data của `project_wbs.md` |
+
+Mọi refuse logic ở Bước 2 (single source). Bước 0 chỉ collect.
+
+---
+
+### Bước 1 — Gather signals (interactive Q&A)
+
+Hỏi dev tuần tự, **cheap → expensive**. Skip câu nào có thể infer từ câu trước hoặc từ state map.
+
+| # | Câu hỏi | Signal | Skip rule |
+|---|---|---|---|
+| 1 | "1 câu mô tả feature/việc cần làm?" | `intent_text` + LLM-classify `change_type` ∈ {new-behavior, bug-fix, refactor, chore, hotfix} | provided as `$ARG` |
+| 2 | "Touch module nào? (chọn từ `wbs_module_list` / multiple / unsure)" | `target_module`, `cross_module_surface` | suy rõ từ intent |
+| 3 | (nếu change_type=hotfix) "Có nằm trong 5 loại preset: typo / config / log-level / lint / test-fix?" | `is_express_eligible` | change_type ≠ hotfix |
+| 4 | (auto) Grep `project_wbs.md` cho id match keyword trong intent | `wbs_id_match` (id hoặc null) | — |
+| 5 | "Scope: ≤3 unit hay >3?" | `scope_attestation` | change_type=hotfix |
+| 6 | (nếu target_module touch contract — INT-* hoặc intent mention API) "Có đổi response shape của contract đã có không?" | `breaks_existing_contract` | non-API rõ ràng |
+| 7 | "Đụng tiền / auth / RBAC / PII không?" | `touches_critical_domain` → drive Mandatory ATDD | clearly cosmetic |
+| 8 | (nếu intent có keyword regulator/compliance/audit) "Audience demo: internal / customer / regulator?" | `demo_audience` | không có keyword |
+| 9 | (nếu target_module UI hoặc intent UI) "Reuse UX journey hay introduce actor/flow mới?" | `introduces_new_actor` | non-UI |
+
+Vagueness/multi-feature check inline → trigger refuse case 2/3 ở Bước 2.
+
+---
+
+### Bước 2 — HARD GATES (single source for refusal)
+
+Áp theo thứ tự, refuse ngay khi match. Output: `❌ {reason} → unblock: {command}`.
+
+| # | Trigger | Unblock |
+|---|---|---|
+| 1 | `!wbs_present` | `/bmad-create-prd` → `/bmad-create-epics-and-stories` → `/ntapp-architecture-design` |
+| 2 | `intent_text` thiếu (verb + object + module hint) sau Q1-Q2 | "Viết 1 đoạn problem statement (vấn đề + actor + outcome), re-run." |
+| 3 | LLM phát hiện intent ≥2 goals không liên quan | "Split intent, re-run per feature." |
+| 4 | `breaks_existing_contract=yes` | "Module 0 contract change → escalate SA + Compliance. Stage 2 re-run với Module 0 update, KHÔNG triagable." |
+| 5 | `target_module` không có trong `wbs_module_list` (module mới) | "Module mới → Stage 2 Agent C re-lock WBS, sau đó re-run triage." |
+| 6 | `change_type=new-behavior` AND `!wbs_id_match` AND không phải hotfix | "Unit mới chưa trong WBS. Amend WBS bằng `/ntapp-architecture-design --append` (mode nhẹ — merge unit mới + audit + sync HLD §3.2.0, KHÔNG re-run full pipeline). Nếu unit chạm contract/boundary Module 0 → append escalate sang FULL re-lock. Sau khi amend → re-run triage." |
+| 7 | `target_module=INT` AND `!module0_present` | "Module 0 missing — finish Stage 2 trước." |
+
+WARN-only (không refuse): `wbs_unit_count ≥ 15` OR `wbs_module_list.size ≥ 5` → ghi vào decision file: "Phase 1 threshold reached → cân nhắc Phase 1.5 trước khi pile thêm feature." Tiếp tục triage.
+
+---
+
+### Bước 3 — Lane selection
+
+Pass Bước 2 → áp decision tree (first-match wins):
+
+```
+if change_type=hotfix AND is_express_eligible:
+    → LANE 1 (Express)
+
+elif change_type ∈ {bug-fix, refactor, chore}
+     AND scope_attestation=≤3
+     AND wbs_id_match
+     AND !touches_critical_domain:
+    → LANE 2 (Path B quick-dev)
+
+elif wbs_unit_count ≤ 3:
+    → LANE 4 trigger-A (Ad-hoc per-unit — project PoC scale)
+
+elif wbs_id_match AND active_slice_count > 0:
+    if id ∈ active SLICE-N (parse SLICE-*.md):
+        → LANE 3 (Full per-slice loop — resume SLICE-N)
+    else:
+        → ADVISORY: "Unit trong WBS nhưng không thuộc slice active.
+                     Chạy /ntapp-slice-planning --rerun để re-balance."
+
+elif change_type=new-behavior
+     AND scope_attestation=≤3
+     AND target_module ∈ wbs_module_list
+     AND breaks_existing_contract=no
+     AND !introduces_new_actor:
+    → LANE 4 trigger-B (Ad-hoc per-unit — per-feature contained)
+
+else:
+    → LANE 3 (default — Full per-slice loop)
+```
+
+---
+
+### Bước 4 — Lane modifiers
+
+#### 4.1 — Resolve DS của feature (chỉ chạy khi target là UI module)
+
+Chạy SAU Bước 1-3 vì cần `target_module` + `wbs_id_match`. Thủ tục chuẩn: `design-system/_shared/ds-resolution.md` **nhánh B** — triage KHÔNG tự chế logic resolve.
+
+- `ds_systems` chỉ có **1 entry** (legacy không registry, hoặc registry 1 system) → `ds_id_target` = system đó, `ds_bootstrap_done = ds_bootstrap_map[đó]`. **Hành vi y hệt trước multi-DS.**
+- **≥2 systems** → match theo thứ tự tín hiệu B.4, dừng ở tín hiệu đầu tiên cho kết quả DUY NHẤT:
+  1. thẻ `<br>- repo: <code-repo>` ở Cluster Header của cluster chứa `wbs_id_match` trong `project_wbs.md` → khớp `systems.{ds}.code_repo`;
+  2. `id_prefixes` — longest-prefix match trên `wbs_id_match`;
+  3. `target_module` ∈ `systems.{ds}.modules`;
+  4. `default_ds`.
+- Tín hiệu 1 mâu thuẫn 2/3 (config drift) → **KHÔNG chọn im lặng**: `ds_bootstrap_done = unknown`, ghi vào decision file "registry hints ↔ thẻ WBS `repo:` lệch nhau — DSO sửa trước khi build".
+- Không tín hiệu nào khớp (feature chưa có unit trong WBS, cluster thiếu thẻ `repo:`) → `ds_bootstrap_done = unknown`, KHÔNG đoán.
+
+`unknown` là advisory, **không refuse** — triage vẫn emit modifier dưới dạng liệt kê ứng viên. STOP-hỏi-HITL thật sự thuộc về Stage 4a/4b (nhánh B), nơi unit đã xác định.
+
+#### 4.2 — Injection
+
+Sau khi chọn lane, áp injection (additive, không đổi lane):
+
+| Condition | Inject |
+|:--|:--|
+| `touches_critical_domain=true` AND lane ∈ {2, 3, 4} | "`/bmad-testarch-atdd` BEFORE first commit (Mandatory ATDD)" |
+| `demo_audience=regulator` | "`/bmad-testarch-nfr` + `/bmad-testarch-trace` BEFORE sign-off" |
+| `introduces_new_actor=true` AND lane=3 | "`/ntapp-ux-sketch` BEFORE `/ntapp-technical-design`" |
+| `ds_bootstrap_done=false` AND UI module | "`/ntapp-ds-bootstrap` FIRST cho DS `{ds_id_target}` (one-time / FE repo `{code_repo}`)" |
+| `ds_bootstrap_done=unknown` AND UI module | "DS của feature chưa resolve được (xem 4.1) — DS chưa bootstrap: {liệt kê `ds_id` có `ds_bootstrap_map=false`}. Chạy `/ntapp-ds-bootstrap` từ FE repo tương ứng trước Stage 4b." |
+| lane=4 trigger-B AND `scope_creep_guardrail=true` | "Write manifest `{manifest_dir}/{id}.yaml` (xem 5b)" |
+
+`atdd_class = mandatory` IFF `touches_critical_domain=true`; else `optional`.
+
+---
+
+### Bước 5 — Emit output
+
+#### 5a. Decision file (LUÔN ghi)
+
+Path: `{triage_output_dir}/{YYYY-MM-DD}-{slug-from-intent}.md`
+
+```markdown
+# Triage Decision — {slug}
+
+**Date:** {YYYY-MM-DD}  **Triaged by:** {git user.name}
+**Intent:** {intent_text}
+
+## Recommended Lane
+**LANE {N} — {name}**{lane-specific suffix, vd "(resume SLICE-N)" hoặc "(trigger-B)"}
+
+## Reasoning
+- {signal_key}={value}  ← {tại sao signal này khiến chọn lane này}
+- ... (list mọi signal đã collect — positive và negative)
+
+## Next Slash Command
+```
+{exact command}
+```
+
+## Subsequent Steps (preview)
+1. {command 1}
+2. {command 2}
+...
+
+## Injected Modifiers
+- {modifier 1} (lý do)
+
+## Refused Paths
+- LANE {X}: blocked — {reason}
+
+## Honest Limits
+{copy 4-5 limit liên quan từ section "Honest limits" dưới}
+```
+
+#### 5b. Manifest (chỉ ghi khi lane=4 trigger-B AND `scope_creep_guardrail=true`)
+
+Path: `{manifest_dir}/{id}.yaml`
+
+```yaml
+# AUTO-GENERATED by /ntapp-feature-triage — DO NOT EDIT manually
+# Pre-commit hook (nếu enabled) enforce bounds tại commit time.
+id: {id}
+type: {new | modify}
+parent_module: {wbs_module}
+parent_epic: {epic_id_from_wbs_lookup}
+scope:
+  units_planned: [{id}]
+  max_units: 2
+attestations:
+  module_0_unchanged: true        # Q6
+  no_new_contract: true
+  no_new_module: true             # verified ở Bước 2 gate 5
+  actor_journey: {reuse-only | minor-delta}  # Q9
+atdd_class: {optional | mandatory}
+demo_audience: {internal | customer | regulator}
+triaged_at: {ISO-8601 timestamp}
+triaged_by: {git user.name}
+triage_log: {relative path to 5a decision file}
+```
+
+Manifest tự nó không enforce gì — cần hook đọc file này (chưa implement). Khi hook chưa có, manifest là documentation + tripwire bằng mắt khi reviewer xem PR.
+
+---
+
+## Honest limits — skill KHÔNG detect được
+
+Ghi vào mọi decision file mục "Honest Limits" (copy các item áp dụng):
+
+- **True scope** — `scope_attestation` là LLM guess + dev claim; thực tế chỉ biết sau DD. Skill không ngăn under-estimation; phụ thuộc dev discipline + code review.
+- **Contract drift implicit** — `breaks_existing_contract` dựa dev honesty; skill không diff được code. Dev nói "no" nhưng thực tế đổi DTO → caught muộn ở Stage 3 contract review.
+- **Cross-slice ripple** — không predict Lane 3 slice force sibling slice re-balance không; emerges ở Stage 5 retro.
+- **DS token gaps** — chỉ flag nếu intent mention visual primitive; gap tinh tế surface ở `/ntapp-ui-generation`.
+- **DS binding tại intake (multi-DS)** — `ds_id_target` resolve từ WBS + registry hints; feature chưa có unit trong WBS, hoặc project ≥2 FE repo mà cluster thiếu thẻ `repo:` → skill chỉ liệt kê ứng viên, không chốt. Binding thật chốt ở Stage 4a/4b (`ds-resolution.md` nhánh B, có STOP HITL).
+- **Test-first discipline trong Lane 2** — `/bmad-quick-dev` không enforce ATDD; skill chỉ recommend.
+- **Stale slice plan vs WBS** — không auto-detect `slices/SLICE-*.md` cũ hơn `project_wbs.md`; dev tự re-run `/ntapp-slice-planning`.
+
+---
+
+## Re-run
+
+Skill idempotent — re-run cùng intent + cùng project state → cùng output (decision file mới timestamp, manifest overwrite). Re-run khi: attestation sai, WBS đổi, scope creep mid-build.
+
+---
+
+## Scope
+
+Skill **chỉ** sinh: decision file (luôn) + manifest (opt-in lane=4 trigger-B). KHÔNG modify: WBS, DD, UI schema, code, hooks, docs khác.

package/skills/NTAPP/.agent/skills/NTAPP-figma-ingest/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: ntapp-figma-ingest
+description: 'Biên dịch một Figma file thành artifact tĩnh deterministic trong spec repo (frame PNG + layout spec JSON + mapping unit↔frame + Figma↔DS map + token gap report) để Stage 4a/4b đọc từ FILE LOCAL, không node nào của slice-loop phải gọi Figma. Chạy NGOÀI slice-loop, ở batch phase sau khi WBS lock. Hai mode: `--tokens-only` (pass 0 — chỉ export Figma Variables/Styles ra W3C JSON làm input cho /ntapp-ds-bootstrap --external-tokens) và full (pass 2 — harvest frame + HITL mapping + spec extract + DS reconcile). Sử dụng khi người dùng nói "ingest figma", "lấy design từ figma", "figma đã vẽ trước", "map figma vào WBS", "đồng bộ figma", "figma ingest", "re-ingest figma".'
+---
+
+# NTAPP Figma Ingest Skill (Stage 0.8 — batch, ngoài slice-loop)
+
+Compiler một chiều: **Figma → artifact spec repo**. Mọi consumer downstream (Stage 4a wireframe transcribe, Stage 4b reuse audit, Stage 5 visual reference) đọc file local đã ingest, KHÔNG gọi Figma.
+
+Không sinh wireframe, không sinh `ui_schema`, không quyết reuse, không ghi `master_token.json` — chỉ **harvest → map → normalize → report gap**.
+
+## Workflow
+
+Follow the instructions in [workflow.md](./workflow.md).

package/skills/NTAPP/.agent/skills/NTAPP-figma-ingest/agents/frame-mapper.md

@@ -0,0 +1,74 @@
+# Persona: Frame Mapper
+
+## 1. Role
+
+Bạn là **Design Ops Analyst** chịu trách nhiệm nối hai thế giới có cách đặt tên hoàn toàn khác nhau: **Figma canvas** (tên frame do designer đặt tự do, có version, có nháp) và **WBS** (ID unit chuẩn hoá, global-unique, đã lock).
+
+Bạn KHÔNG thiết kế UI. Bạn KHÔNG quyết định unit nào cần tồn tại. Bạn chỉ **đề xuất mapping có bằng chứng** rồi đưa người ký.
+
+## 2. Nguyên tắc bất khả xâm phạm
+
+1. **WBS là SSoT của inventory.** Frame không có unit tương ứng KHÔNG bao giờ được "tạo unit mới" — escalate `/ntapp-architecture-design --append`. Để Figma sinh unit là mở đường cho inventory thứ hai và mọi rule pre-commit (Rule 2) sẽ đánh nhau với nó.
+2. **Không đoán mapping.** Đây là loại sai lầm đắt nhất trong cả pipeline: map sai frame → F3 transcribe sai màn → DD sai → code sai, và không có gate nào phía sau bắt được vì mọi artifact đều "hợp lệ". Confidence < HIGH → đưa vào bảng HITL.
+3. **Thiếu frame không phải lỗi.** Ingest từng phần là hợp lệ; unit thiếu frame chỉ đơn giản rơi về author mode ở Stage 4a.
+4. **Bạn không sửa Figma và không sửa WBS.** Chỉ ghi manifest.
+5. **Không kết luận về thứ mình chưa xem.** Unit ngoài scope harvest → giữ nguyên entry cũ, KHÔNG gán `missing`. `missing` nghĩa là "đã xét, Figma không có"; nói `missing` về unit chưa xét là báo cáo sai và hậu quả (Stage 4a âm thầm rơi về author mode) không gate nào bắt được.
+6. **Feature scope chỉ cắt phía WBS.** `--feature` (truyền tay hay bạn suy) không bao giờ được lọc bớt frame — phía Figma chỉ do `scope_pages`/`node_ids` quyết. Hai nguồn cùng quyết scope là công thức mất frame im lặng.
+
+## 3. Tín hiệu mapping (thứ tự áp dụng, dừng ở tín hiệu đầu cho kết quả DUY NHẤT)
+
+| # | Tín hiệu | `matched_by` | Confidence |
+|---|---|---|---|
+| 1 | Tên frame **chứa đúng ID unit** — so sau khi uppercase + bỏ mọi ký tự ngoài `[A-Z0-9-]` (`scr login` ≠ match; `SCR-LOGIN v3` → match) | `exact-id` | **HIGH** |
+| 2 | Name similarity ≥ 0.85 với mô tả unit trong WBS — normalize: bỏ dấu tiếng Việt, lowercase, strip `v\d+`/`final`/`copy`/`draft`/`new` | `name-similarity` | **MEDIUM** |
+| 3 | Vị trí frame trong page khớp thứ tự màn trong `ux_design.md` §4 journey **VÀ** similarity ≥ 0.6 | `journey-order` | **MEDIUM** |
+| 4 | Mapping đã ký ở manifest cũ + tên frame không đổi | `previous-manifest` | **HIGH** |
+| 5 | Không tín hiệu nào | `none` | **LOW** → bắt buộc người map tay |
+
+**Xung đột tín hiệu** (2 unit cùng match 1 frame ở cùng mức, hoặc 1 unit match 2 frame ở cùng mức) → **không tự phá vỡ thế cân bằng**. Đưa cả hai ứng viên vào bảng HITL, ghi rõ score từng bên.
+
+## 4. Bốn case lệch — quyết định của bạn
+
+| Case | Nhận diện | Hành động |
+|---|---|---|
+| **A. Frame mồ côi** | Frame còn lại sau khi mọi unit đã có frame | Hỏi *"nháp hay màn thật?"*. Nháp → `ignore: true` + `ignore_reason`. Màn thật → **STOP escalate WBS** |
+| **B. Unit thiếu frame** | Unit FE trong WBS không match frame nào | `figma_status: missing`. Ghi vào report để 4a biết author mode. **KHÔNG block** |
+| **C. 1 unit ↔ N frame** | Nhiều frame cùng base name, hoặc nhiều variant group trỏ 1 unit | State nhận diện được → `states[]`. Nhiều group thật khác nhau → hỏi group nào canonical, còn lại `ignore` |
+| **D. 1 frame ↔ N unit** | Frame chứa screen + widget nhúng (`WGT-*` có mặt trong WBS nhưng không có frame riêng) | `contains[]`: `{unit_id, node_id}` cho từng widget. Không chỉ được node con → widget đó `missing` |
+
+Case C là case **thường gặp nhất** trong thực tế (designer vẽ empty/loading/error thành frame riêng), và cũng là case có giá trị cao nhất: `states[]` chính là input cho L2 mandatory-states audit ở Stage 4a §2.4.
+
+## 4b. Feature scope — suy đoán khi người dùng không truyền `--feature`
+
+Mục tiêu duy nhất: **bảng HITL ngắn lại** + có dòng coverage. Không phải cơ chế đúng/sai.
+
+1. Chạy tín hiệu mapping (§3) trên full WBS trước.
+2. Lấy các unit match `HIGH`/`MEDIUM` → tra ngược feature/cluster chứa chúng (slice manifest → WBS cluster → journey).
+3. ≥2 unit cùng 1 feature → đó là feature suy đoán. Trình kèm bằng chứng: *"suy từ {N} unit đã match"*.
+4. Đưa câu xác nhận vào **chính bảng HITL đang trình** — tuyệt đối không tạo thêm một vòng hỏi riêng cho việc này.
+5. Suy không ra (0-1 unit match, hoặc rải rác nhiều feature) → giữ full WBS, không hỏi. Bảng dài hơn nhưng không sai, vì luật merge đã chặn ghi đè.
+6. Người bác tên bạn suy → dùng tên họ đưa, lọc lại, trình lại **một** lần. Vẫn không khớp nguồn nào → bỏ lọc, full WBS.
+
+Sai lầm cần tránh: coi feature suy đoán là chân lý rồi **loại** unit khỏi phạm vi xét. Suy đoán chỉ ảnh hưởng cái gì **hiện ra trên bảng**; luật in-scope ở `references/figma-manifest-schema.md` mới là cái quyết định unit nào được ghi lại.
+
+## 5. Output spec
+
+Bảng HITL — mỗi dòng bắt buộc đủ: `WBS unit | Mô tả (WBS) | Frame đề xuất | States | DS | Tín hiệu | Confidence`. Kèm 3 danh sách phụ: **Frame chưa dùng**, **Unit chưa có frame**, **Cần bạn xác nhận** (gộp mọi câu hỏi vào đây — hỏi **một lần**, không hỏi nhiều vòng).
+
+Sau khi người ký → `figma-manifest.yaml` theo `references/figma-manifest-schema.md`. Ghi `matched_by` + `confidence` + `approved_by` + `approved_at` vào từng entry: đây là audit trail để 6 tháng sau còn trả lời được "ai quyết frame này là `SCR-LOGIN`".
+
+## 6. Edge cases
+
+- **Tên frame trùng nhau ở 2 page** (`Product/Login`, `Flows/Login`) → không tự chọn; hỏi kèm tên page. Nếu 1 trong 2 nằm ở page bị `ignore_name_patterns` loại thì đã không tới đây.
+- **Frame tiếng Việt có dấu, unit id tiếng Anh** → normalize theo tín hiệu 2 (bỏ dấu) rồi so với **cột mô tả** WBS (thường cũng tiếng Việt), không so với ID.
+- **Designer dùng SECTION làm nhóm journey** → SECTION không phải màn; lấy các frame con làm candidate, dùng tên SECTION làm tín hiệu journey-order (tín hiệu 3).
+- **`WGT-*` được vẽ thành component (không phải frame)** → hợp lệ: `COMPONENT_SET`/`COMPONENT` được nhận làm candidate cho `WGT-*` (nhưng KHÔNG cho `SCR-*`).
+- **Re-ingest sau khi designer rename frame** → tín hiệu 4 fail (tên đổi) → rơi xuống tín hiệu 1/2. Nếu match lại đúng unit cũ với confidence HIGH → carry over mapping, ghi `renamed_from` để audit. Nếu không → hỏi người.
+- **Unit đã có DD ký với `figma_ref` trỏ node_id cũ, giờ node_id đổi** (designer xoá + vẽ lại frame) → giữ mapping mới nhưng ghi `node_id_changed: true`; step-07 sẽ tính checksum mới → Hook 3 báo drift → người xử lý DD. KHÔNG tự im lặng.
+
+## 7. Constraints
+
+- **U5 (no fabrication)** là rule sống-còn của persona này. Không có tín hiệu → nói không có, không "cảm thấy giống".
+- Không đọc/ghi code repo (U3). Không ghi ngoài `_reference/figma/`.
+- Không đọc raw document tree vào context (U7) — chỉ làm việc trên `frames_raw.json` đã prune.
+- Không tự thêm/sửa/xoá dòng nào trong `project_wbs.md`.

package/skills/NTAPP/.agent/skills/NTAPP-figma-ingest/references/figma-manifest-schema.md

@@ -0,0 +1,151 @@
+# Figma Manifest Schema — `figma-manifest.yaml`
+
+> **Version:** v1.0. Đây là **CONTRACT** giữa `ntapp-figma-ingest` (producer) và 4 consumer: Stage 4a `ntapp-feature-design`, Stage 4b `ntapp-ui-generation`, Stage 5 `dev`, và Hook 3 `stage3_input_gate.sh`.
+> Đổi schema = đổi contract → phải patch cả 4 consumer. Thêm field optional thì không.
+
+## Vị trí
+
+`{ds_root}/_reference/figma/figma-manifest.yaml` — **per DS root**, mỗi file chỉ chứa unit thuộc DS đó.
+
+Single-DS (không có `registry.yaml`) → đúng 1 file tại family root. Multi-DS → N file; consumer resolve DS root của unit theo `_shared/ds-resolution.md` (nhánh B cho skill, nhánh D cho hook) rồi mới đọc manifest tương ứng.
+
+## Schema
+
+```yaml
+schema_version: "1.1"
+ds_id: web-admin                  # null nếu single-DS
+file_key: AbC123XyZ
+figma_version: "1234567890"       # version PINNED của cả run (U4)
+figma_last_modified: 2026-08-01T09:12:00Z
+ingested_at: 2026-08-05T14:03:11Z
+source_mode: api                  # api | manual | mcp
+
+# Scope của LẦN INGEST GẦN NHẤT — quyết định unit nào được re-evaluate, unit nào
+# giữ nguyên (xem §Merge semantics). Thiếu block này = manifest v1.0 cũ → coi như
+# scope toàn file (mọi unit in-scope).
+last_scope:
+  pages: ["Thanh toán"]           # [] = toàn file
+  node_ids: []
+  feature: "Thanh toán"           # null nếu không truyền --feature
+  units_in_scope: [SCR-PAY-01, SCR-PAY-02, SCR-PAY-03]
+
+units:
+  - unit_id: SCR-LOGIN            # BẮT BUỘC — phải tồn tại trong project_wbs.md
+    figma_status: mapped          # mapped | missing | not_in_scope | stale | ignored
+    node_id: "12:340"             # null khi figma_status != mapped
+    base_name: "SCR-LOGIN v3"     # tên frame nguyên văn trong Figma
+    page: Product
+    matched_by: exact-id          # exact-id | name-similarity | journey-order | previous-manifest | manual
+    confidence: HIGH              # HIGH | MEDIUM | LOW
+    approved_by: ngoanh           # ai ký ở HITL step-03
+    approved_at: 2026-08-05T13:58:02Z
+    checksum: "sha256:9f2a1c0b4e7d8a35"
+    drift: false                  # true khi checksum đổi so với lần ingest trước
+    states:
+      - state: default            # default | empty | loading | error | success | <chuỗi tự do>
+        node_id: "12:340"
+        state_recognized: true
+        frame_exported: true
+        frame: _reference/figma/frames/SCR-LOGIN.png        # relative tới DS root (U2)
+      - state: error
+        node_id: "12:411"
+        state_recognized: true
+        frame_exported: true
+        frame: _reference/figma/frames/SCR-LOGIN__error.png
+    spec: _reference/figma/specs/SCR-LOGIN.json
+    contains: []                  # case D — widget nhúng trong frame này
+
+  - unit_id: WGT-FILTER
+    figma_status: mapped
+    node_id: "12:355"             # node con bên trong frame của SCR-LIST
+    parent_unit: SCR-LIST         # chỉ có ở unit đến từ contains[]
+    # ... phần còn lại như trên
+
+  - unit_id: SCR-EXPORT
+    figma_status: missing         # ĐÃ XÉT, Figma thật sự không có frame → 4a author mode
+    node_id: null
+    reason: "Không frame nào match ở lần ingest 2026-08-05"
+    last_evaluated_at: 2026-08-05T13:58:02Z
+
+  - unit_id: SCR-LOGIN-OLD
+    figma_status: not_in_scope    # CHƯA XÉT lần này (ngoài scope harvest) — KHÁC missing
+    node_id: null
+    reason: "Ngoài scope ingest 2026-08-05 (pages=[Thanh toán])"
+    last_evaluated_at: 2026-07-20T10:00:00Z   # lần cuối THỰC SỰ được xét
+
+ignored_frames:
+  - base_name: Sandbox
+    node_id: "44:12"
+    page: Product
+    ignore_reason: "designer xác nhận là nháp (HITL step-03)"
+
+summary:
+  mapped: 12
+  missing: 2
+  ignored: 4
+  frames_exported: 18
+  token_gaps: 7
+  contrast_fails: 1
+```
+
+## Field bắt buộc (step-07 validate; thiếu → STOP)
+
+Cấp file: `schema_version`, `file_key`, `figma_version`, `ingested_at`, `source_mode`, `last_scope`, `units`, `summary`.
+Cấp unit: `unit_id`, `figma_status`. Khi `figma_status: mapped` thêm: `node_id`, `base_name`, `matched_by`, `confidence`, `approved_by`, `checksum`, `states` (≥1), `spec`.
+
+## Merge semantics — manifest được MERGE, KHÔNG replace (v1.1)
+
+Đây là bất biến quan trọng nhất của schema. Ingest hầu như luôn chạy **hẹp scope** (feature mới → 1 page Figma), nên nếu step-07 ghi đè manifest thì mọi unit của feature cũ bị hạ xuống `missing` → Stage 4a im lặng rơi về author mode dù Figma vẫn còn frame, và Hook 3 **không bắt được** (nó chỉ so checksum khi status là `mapped`). Lỗi loại này không ai báo, chỉ là chất lượng DD tự dưng kém đi.
+
+**Định nghĩa "in-scope" của một unit ở lần ingest hiện tại** (xét theo thứ tự, dừng ở điều kiện đầu tiên đúng):
+
+| # | Điều kiện | Kết luận |
+|---|---|---|
+| 1 | Có `--feature` **và** unit ∈ danh sách unit của feature đó | in-scope |
+| 2 | Có `--feature` **và** unit ∉ danh sách đó | **out-of-scope** |
+| 3 | Không `--feature`, harvest scope là toàn file (`pages: []` + `node_ids: []`) | in-scope |
+| 4 | Entry cũ của unit có `page` ∈ pages đã harvest lần này | in-scope |
+| 5 | Unit chưa có entry nào trong manifest cũ | in-scope (ứng viên mới) |
+| 6 | Còn lại | **out-of-scope** |
+
+**Luật ghi:**
+
+- Unit **in-scope** → re-evaluate đầy đủ; kết quả có thể là `mapped` / `missing` / `ignored`. Set `last_evaluated_at` = giờ hiện tại.
+- Unit **out-of-scope** → **giữ nguyên entry cũ verbatim**. KHÔNG đổi `figma_status`, KHÔNG đổi `checksum`, KHÔNG chạm `last_evaluated_at`.
+- Unit out-of-scope mà **chưa từng** có entry (mới xuất hiện trong WBS, chưa ingest lần nào) → ghi `figma_status: not_in_scope` + `reason` nêu scope đã loại nó.
+
+**`missing` vs `not_in_scope` — hai thứ khác nhau, đừng trộn:**
+
+| | Nghĩa | Stage 4a | Hook 3 |
+|---|---|---|---|
+| `missing` | Đã xét, Figma **thật sự không có** frame cho unit này | author mode (đúng ý) | pass |
+| `not_in_scope` | **Chưa xét** lần này — không biết Figma có gì | dùng entry cũ nếu có; không có thì author mode | **WARN** nếu DD có `figma_ref` (chưa verify được drift) |
+
+## Bất biến
+
+1. **`unit_id` phải tồn tại trong `project_wbs.md`.** Manifest không bao giờ là nguồn khai sinh unit.
+2. **`checksum` chỉ do step-07 ghi** — công thức ở step-07 Stage 7.1. Manifest có unit `mapped` mà `checksum` rỗng = manifest chưa finalize → consumer coi như chưa ingest.
+3. **Không lưu URL Figma đầy đủ, không lưu signed URL S3** (U6). Chỉ `file_key` + `node_id`; ai cần mở thì dựng link từ 2 mảnh đó.
+4. **Path trong manifest là relative tới DS root** (U2) — portability cross-machine.
+5. **`figma_version` cấp file là version của lần ingest gần nhất.** Unit out-of-scope giữ dữ liệu từ version cũ hơn — hợp lệ và có chủ ý (`last_evaluated_at` cho biết dữ liệu của unit đó cũ tới đâu). Đừng suy ra "mọi unit đều ở version này".
+6. **Manifest MERGE, không replace** (xem §Merge semantics). Step-07 ghi đè toàn file = bug.
+
+## Consumer đọc gì
+
+| Consumer | Field dùng | Hành vi |
+|---|---|---|
+| Stage 4a `feature-design` step-02 | `units[].figma_status`, `spec`, `states[].frame` | `mapped` → transcribe mode (đọc spec + frame). `missing`/`not_in_scope`/`stale` → author mode như cũ |
+| Stage 4a (ghi ngược vào DD §1) | `file_key`, `node_id`, `figma_version`, `checksum` | Ghi thành `figma_ref` trong DD — nguồn so sánh của Hook 3 |
+| Stage 4b `ui-generation` step-01 | (qua `figma-ds-map.md`, không đọc manifest trực tiếp) | Bậc C-1 reuse ladder |
+| Stage 5 `dev` | `states[].frame` | Visual reference qua link trong story. CẤM copy CSS (Rule 4) |
+| Hook 3 `stage3_input_gate.sh` | `units[].unit_id`, `figma_status`, `checksum` | `mapped` + checksum lệch → **block**. `not_in_scope` + DD có `figma_ref` → **warn** (chưa verify được). `missing` → pass |
+
+## Quan hệ với `figma_ref` trong DD
+
+DD (Stage 4a) ghi ở §1:
+
+```markdown
+- **figma_ref:** `AbC123XyZ` / node `12:340` / version `1234567890` / checksum `sha256:9f2a1c0b4e7d8a35`
+```
+
+Hook 3 so `checksum` trong dòng này với `units[].checksum` của manifest hiện tại. Lệch → Figma đã đổi sau khi DD ký → block kèm hint chạy lại `/ntapp-figma-ingest`. Đây là toàn bộ phần Figma nằm trong slice-loop: **read-only, 0 network**.