@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-architecture-design/workflow.md

@@ -0,0 +1,235 @@
+# Architecture Design Workflow (NTAPP Multi-Agent Edition)
+
+**Goal:** Tạo tài liệu Thiết kế Kiến trúc Tổng thể (HLD) hoàn chỉnh bằng chuẩn NTAPP Final Template thông qua hệ thống 6 Agent (A/B/C/D/E/F) chuyên biệt hoạt động tuần tự.
+
+**Your Role:** Bạn đóng vai **Agent E (Orchestrator)** — điều phối tuần tự Agent A → B → C → D → F, vận hành các quality gate, và assembly bản HLD cuối cùng. Bạn là điểm chạm duy nhất với người dùng trong toàn workflow.
+
+**Iron Rules:** Toàn workflow tuân thủ [principles/iron_rules.md](./principles/iron_rules.md). Đọc file này trước khi thực thi bất kỳ step nào.
+
+---
+
+## WORKFLOW ARCHITECTURE — Progressive disclosure
+
+- File này giữ KHUNG điều phối (mode + roster + bản đồ + rule + launch). Chi tiết thực thi nằm TRONG từng step file `./steps/`.
+- ⛔ Đọc ĐÚNG MỘT step mỗi lần. Hoàn tất step hiện tại (gồm mọi PAUSE/GATE) RỒI mới đọc step kế qua pointer `**Next:**` ở cuối step. KHÔNG đọc trước nhiều step. State chuyển tiếp qua `part_*.md` trong `{intermediate_folder}`, không qua việc giữ instruction trong context.
+
+---
+
+## MODE SELECTION (Agent E đọc ĐẦU TIÊN)
+
+Skill có 2 mode. Agent E xác định mode từ user message **trước khi** chạy bất kỳ step nào:
+
+| Mode | Trigger | Khi nào dùng |
+|---|---|---|
+| **FULL** (default) | "thiết kế kiến trúc" / "tạo HLD" / không có flag | Lần đầu tạo HLD, hoặc overhaul toàn bộ kiến trúc |
+| **APPEND** | `--append`, "thêm unit vào WBS", "amend WBS", "bổ sung feature vào kiến trúc" | Đã có HLD + WBS lock; cần thêm 1 vài unit mới mà **KHÔNG** đổi contract Module 0 |
+
+- **FULL mode** → chạy full pipeline A→B→C→D→F (mục [EXECUTION](#execution)).
+- **APPEND mode** → chạy luồng rút gọn ở mục [APPEND MODE EXECUTION](#append-mode-execution-incremental-wbs-amendment). **Bỏ qua** mục EXECUTION đầy đủ.
+
+> **Vì sao có APPEND:** Sau khi WBS lock, mỗi feature unit mới (vd từ `/ntapp-feature-triage` hard-gate 6) trước đây phải re-run full pipeline (HLD → Module 0 → WBS → audit → assembly) — quá nặng và cascade Module 0 không cần thiết khi unit mới là leaf nằm gọn trong module sẵn có. APPEND là entry point nhẹ: chỉ merge WBS + audit + sync HLD §3.2.0, escalate FULL **chỉ khi** chạm contract/boundary.
+
+---
+
+## ROSTER & ROLES
+
+| Agent | Role | Steps Owned |
+|---|---|---|
+| **A** | Context Strategist | 02 |
+| **B** | Research Scout (Conditional) | 03 |
+| **C** | System Architect | 04.1, 04.2 |
+| **D** | Implementation & Security Lead | 05 |
+| **E** | Orchestrator + QA Gatekeeper | 01, 04.1b, 07 |
+| **F** | Integration Architect | 06 |
+
+---
+
+## PIPELINE MAP (neo thường trực — 1 dòng/step, KHÔNG chi tiết)
+
+Mỗi step là một file độc lập trong `./steps/`, mở đầu bằng `> **Acting as:** [Agent X]` trỏ persona, kết thúc bằng pointer `**Next:**` tới step kế (step cuối là TERMINAL).
+
+| # | Step file | Agent | Output | Gate |
+|---|---|---|---|---|
+| 01 | steps/step-01-init.md | E | Context Summary (clarify gaps) | intake — user confirm Context + Tech Stack |
+| 02 | steps/step-02-strategy.md | A | part_02_context_strategy.md | **G1** NFR Completeness |
+| 03 | steps/step-03-research.md | B (conditional) | part_03_tech_research.md | user confirm tech stack (nếu research) |
+| 04.1 | steps/step-04.1-architecture-global.md | C | part_04.1_global_architecture.md + project_wbs.md | handshake → 04.1b; **G3** L1/L2 self-check |
+| 04.1b | steps/step-04.1b-wbs-audit.md | E | project_wbs.md "Audited & Locked" | **G2** WBS Coverage |
+| 04.2 | steps/step-04.2-architecture-modules.md | C | part_04.2_modular_deepdive.md | — |
+| 05 | steps/step-05-implementation-security.md | D | part_05_implementation_security.md | — |
+| 06 | steps/step-06-module0.md | F | 00_system_connectivity_integration.md (+ archive) | R8 Sync Check |
+| 07 | steps/step-07-assembly.md | E | architecture_design.md (+ archive) | **G4** Quantitative Audit (TERMINAL) |
+
+Chuỗi (FULL mode): **01 → [G1] 02 → 03 (conditional — tự pass-through nếu không kích hoạt) → 04.1 → [G2] 04.1b → 04.2 → 05 → 06 → 07 [G4]**.
+Cổng người-dùng: **intake** (Step 01) + **xác nhận tech stack** (Step 03 nếu research) + **trình bày HLD cuối** (Step 07). Các gate G1–G4 + R8 là QA/self-check (FAIL → loop về owner — KHÔNG phải pointer `**Next:**`).
+
+---
+
+## INITIALIZATION
+
+### Phân giải cấu hình (Configuration Resolution)
+
+Trước khi chạy bất kỳ step nào, Agent E PHẢI resolve config theo cascade 3 layer (ưu tiên cao → thấp).
+
+#### Bước 0 — Resolve `{project-root}`
+
+Walk up từ `cwd` tìm marker folder:
+1. Nếu thấy `_bmad/` → đó là `{project-root}`.
+2. Nếu thấy `.git/` → đó là `{project-root}`.
+3. Nếu lên đến `/` không thấy gì → fallback `cwd` + log warning: "⚠️ Không tìm thấy marker (`_bmad/` hoặc `.git/`), dùng cwd làm project-root".
+
+#### Layer 1 — BMad project config
+
+Đọc `{project-root}/_bmad/bmm/config.yaml` nếu tồn tại. Lookup keys:
+- `project_name`
+- `planning_artifacts`
+
+BMad dùng placeholder `{project-root}` trong values → Agent E thay bằng absolute path đã resolve ở Bước 0.
+
+#### Layer 2 — Skill family config (override)
+
+Đọc `{project-root}/.bmm-config.yaml` nếu tồn tại. Tìm section `ntapp-architecture-design:`. Override giá trị từ Layer 1 nếu có.
+
+Schema mong đợi:
+```yaml
+ntapp-architecture-design:
+  project_name: <string>          # optional, override Layer 1
+  planning_artifacts: <path>      # optional, override Layer 1
+```
+
+#### Layer 3 — Default + Interactive (fallback)
+
+Khi cả Layer 1 và Layer 2 đều miss biến cần → DỪNG, hỏi user (Pause & Wait):
+
+```markdown
+## ⚙️ SKILL CONFIG MISSING — Setup lần đầu
+
+Tôi không tìm thấy config (`_bmad/bmm/config.yaml` hoặc `.bmm-config.yaml`).
+Cần xác định 2 thông tin sau (ENTER để chấp nhận default):
+
+[Q1] **project_name** (default: `{tên folder của project-root}`)?
+[Q2] **planning_artifacts** path cho artifact thiết kế
+     (default: `{project-root}/output/architecture/`)?
+
+→ Sau khi anh trả lời, tôi sẽ ghi vào `{project-root}/.bmm-config.yaml`
+   để lần sau không hỏi lại.
+```
+
+Sau khi user trả lời:
+- Tạo/append vào `{project-root}/.bmm-config.yaml` section `ntapp-architecture-design:`.
+- mkdir -p `{planning_artifacts}/architecture_design_parts/`.
+
+#### Biến runtime cuối cùng
+
+Sau cascade, các biến phải có giá trị:
+
+| Biến | Nguồn | Ghi chú |
+|---|---|---|
+| `project_name` | Layer 1/2/3 | Tên dự án — hiển thị trong header HLD |
+| `planning_artifacts` | Layer 1/2/3 | Absolute path (đã resolve `{project-root}`) |
+| `intermediate_folder` | Auto-derive | = `{planning_artifacts}/architecture_design_parts/` |
+| `template_path` | Hardcode | `./templates/architecture_design_final_template.md` — resolve relative to **skill root** (folder chứa workflow.md), KHÔNG phải cwd |
+| `agent_personas_path` | Hardcode | `./agents/` — relative to skill root |
+| `iron_rules_path` | Hardcode | `./principles/iron_rules.md` — relative to skill root |
+| `date` | System | Format ISO 8601 `YYYY-MM-DD` |
+
+### Output Naming Convention (Dual-Write)
+
+Mọi output cuối cùng (HLD + Module 0) đều ghi 2 bản: canonical (latest) + archive (versioned snapshot).
+
+| Output | Canonical (latest) | Archive (history) |
+|---|---|---|
+| HLD final | `{planning_artifacts}/architecture_design.md` | `{planning_artifacts}/archive/architecture_design_v{N}.md` |
+| Module 0 | `{planning_artifacts}/00_system_connectivity_integration.md` | `{planning_artifacts}/archive/00_system_connectivity_integration_v{N}.md` |
+| Intermediate parts | `{intermediate_folder}/part_*.md` | (không archive — overwrite mỗi run) |
+
+**Versioning logic:** Detect `N_next` bằng `ls archive/{base}_v*.md` → `max(N) + 1` (hoặc `1` nếu archive rỗng).
+
+**Module 0 write constraint:** Tuân thủ [Iron Rules R8](./principles/iron_rules.md#r8-contract-lock-khoá-hợp-đồng-tích-hợp) — Module 0 chỉ được write theo cascade từ HLD hoặc reconcile drift.
+
+### Quality Gates Map
+
+Bảng định nghĩa Gate (G1-G4) tại [`principles/iron_rules.md`](./principles/iron_rules.md#r6-handshake--gate-trạm-kiểm-soát) **R6 — Handshake & Gate** (SSoT). Không lặp body ở đây để tránh drift.
+
+---
+
+## GLOBAL RULES (bất biến — áp dụng mọi step FULL mode)
+
+- ✅ Toàn workflow tuân thủ [Iron Rules R1–R9](./principles/iron_rules.md) — đọc trước khi thực thi bất kỳ step nào.
+- ✅ Agent E là điểm chạm duy nhất với người dùng; mỗi step hoá thân đúng persona trong [`./agents/`](./agents/).
+- ✅ **NO FABRICATION (R3):** không bịa số liệu/thực thể/giao thức ngoài input đã xác nhận — thiếu thì đánh `[TBD]` hoặc hỏi user.
+- ✅ **Dual-write (R8):** mọi output cuối (HLD + Module 0) ghi 2 bản — canonical (latest) + archive versioned.
+- ⛔ Đọc đúng MỘT step file mỗi lần; chỉ đọc step kế qua pointer `**Next:**` khi step hiện tại xong + qua cổng (nếu có). State chuyển tiếp qua `part_*.md` trong `{intermediate_folder}`, KHÔNG qua việc giữ instruction trong context.
+
+---
+
+## APPEND MODE EXECUTION (Incremental WBS Amendment)
+
+> **Acting as:** Agent E điều phối; Agent C thực thi merge WBS; Agent F **không** tham gia (không có contract change ở mode này).
+> **Tuân thủ:** [Iron Rules](./principles/iron_rules.md) — R1 (Verbatim), R2 (Zero-summarization), R4 (Traceability), R5 (Consistency), R8 (Contract Lock).
+> **Mục tiêu:** Thêm 1 vài work unit mới vào `project_wbs.md` đã lock + sync HLD §3.2.0, **KHÔNG** re-run toàn pipeline. Entry point nhẹ cho `/ntapp-feature-triage` hard-gate 6.
+
+### A1 — Pre-flight (Agent E)
+
+1. Resolve config theo cascade 3 layer — **giống FULL mode** [INITIALIZATION](#initialization) (cùng `project_name`, `planning_artifacts`, `intermediate_folder`).
+2. Verify `{planning_artifacts}/project_wbs.md`:
+   - **KHÔNG tồn tại** → STOP: *"Chưa có WBS để append. Chạy FULL mode (`/ntapp-architecture-design`) trước."*
+   - **Tồn tại + invalid format** (thiếu Function Decomposition Tree hoặc Coverage Matrix) → escalate như [step-04.1 §3.1](./steps/step-04.1-architecture-global.md) (backup `.bak` / user tự sửa). KHÔNG đụng file trước khi user confirm.
+   - **Tồn tại + valid** → tiếp A2.
+3. Verify HLD canonical `{planning_artifacts}/architecture_design.md` tồn tại (cần để re-inject §3.2.0 ở A5). Thiếu → WARN: append WBS được nhưng HLD chưa có để sync — gợi ý chạy FULL.
+
+### A2 — Clarify new unit(s) (Agent E — Pause & Wait)
+
+Hỏi user cho **mỗi** unit mới (cheap → expensive). KHÔNG tự suy đoán (R3):
+
+- `module_type` ∈ 4-type (`backend-service` / `frontend-app` / `integration-contract` / `infrastructure`).
+- `id` theo prefix convention tương ứng (`BE-{MOD}-NN` / `SCR-{NAME}` / `WGT-{NAME}` / `INT-{SRC}-NN`). Verify id **chưa** tồn tại trong WBS (append, không overwrite).
+- `parent_module` — **phải** ∈ module list declared trong WBS hiện tại. Module **MỚI** → STOP, escalate FULL mode (Agent C cần re-cluster + redraw L1/L2). Đây là biên giới append.
+- `parent_epic` / story ID từ PRD/Epics (Traceability R4).
+- Relations: screen ghi `consumes:`, widget cross-screen ghi `used_by:`, contract ghi `provider:` + `consumers:` (format ở [template mục 0](./templates/coverage_matrix_wbs.md)).
+- Mô tả ngắn + data domain chính.
+
+### A3 — CONTRACT-IMPACT GATE (Agent E — biên giới append vs full cascade)
+
+APPEND **chỉ** hợp lệ khi unit mới KHÔNG đổi contract/boundary đã lock. Refuse → escalate FULL khi BẤT KỲ điều kiện sau:
+
+- `module_type = integration-contract` (INT-*) → contract mới = Module 0 surface change.
+- Unit mới đổi response shape / field của contract INT-* đã có.
+- Unit mới thêm External System chưa có trong sơ đồ L1/L2 (đổi system boundary).
+
+→ Output: *"❌ Unit này chạm contract/boundary Module 0 → KHÔNG append được. Chạy FULL mode để cascade HLD + Module 0 (Step 06)."* (mirror `/ntapp-feature-triage` hard-gate 4 + Iron Rule R8.)
+
+Pass gate → unit là **leaf nằm gọn trong container/module sẵn có** → A4.
+
+### A4 — Merge WBS + Audit (Agent C → Agent E)
+
+1. Agent C áp **WBS File Management Rule** ([step-04.1 §3.1](./steps/step-04.1-architecture-global.md), nhánh *"File ĐÃ tồn tại + valid"*): giữ nguyên row cũ, **append** row mới vào CẢ Function Decomposition Tree + Coverage Matrix. TUYỆT ĐỐI KHÔNG overwrite toàn file.
+2. Agent E chạy **[Step 04.1b WBS Audit (G2)](./steps/step-04.1b-wbs-audit.md)** trên WBS đã merge — scope: coverage của unit mới + consistency toàn cục (relations không orphan, prefix khớp `module_type`, traceability về epic). FAIL → loop về Agent C sửa, KHÔNG đi A5.
+
+### A5 — Sync HLD + version bump (Agent E)
+
+1. WBS là SSoT cho HLD §3.2.0 → re-inject **Tree + Bảng verbatim** vào `architecture_design.md`, **chỉ** §3.2.0; KHÔNG đụng section khác (R1 Verbatim + R2 Zero-summarization).
+2. Dual-write archive: bump `archive/architecture_design_v{N+1}.md` (versioning logic ở [INITIALIZATION → Output Naming](#output-naming-convention-dual-write)).
+3. **Module 0 KHÔNG re-run** — đã gate ở A3 (không có contract change). Nếu cần cascade Module 0 thì A3 đã escalate FULL, không tới đây.
+
+### A6 — Downstream notice (Agent E — nhắc, KHÔNG tự chạy)
+
+- **Slice plan:** chạy `/ntapp-slice-planning` (re-run mode) để assign unit mới vào slice — slice-planning đã có re-run mode cho *"WBS thêm unit mới"*.
+- **Re-run triage:** `/ntapp-feature-triage` cho unit mới (giờ đã có `wbs_id_match` → triage route được lane).
+
+### Exit Criteria (APPEND)
+
+- [ ] Unit mới xuất hiện trong CẢ Tree + Bảng của `project_wbs.md`; row cũ nguyên vẹn.
+- [ ] WBS Audit G2 PASS trên file đã merge.
+- [ ] HLD §3.2.0 đã re-inject + archive version bump (chỉ khi HLD tồn tại).
+- [ ] KHÔNG có contract/Module 0 change (nếu có → đã escalate FULL ở A3).
+
+---
+
+## EXECUTION
+
+> **Áp dụng cho FULL mode.** APPEND mode dùng mục [APPEND MODE EXECUTION](#append-mode-execution-incremental-wbs-amendment) ở trên.
+
+Sau khi resolve config ([INITIALIZATION](#initialization)) và xác nhận **mode = FULL** → khởi động pipeline tuần tự theo PIPELINE MAP. Đọc đúng MỘT step mỗi lần; mỗi step tự trỏ step kế qua `**Next:**` ở cuối file. KHÔNG đọc trước nhiều step.
+
+**Next:** Read fully and follow `./steps/step-01-init.md`

package/skills/NTAPP/.agent/skills/NTAPP-bug-fix-engine/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: NTAPP-bug-fix-engine
+description: 'Engine fix MỘT bug đã localize trên một WBS unit — ceremony-adaptive (gate bật/tắt theo lane / atdd_class / contract-change, không full-gate đồng đều; `severity` chỉ là tín hiệu phụ — ordering + fallback suy lane, không trực tiếp bật gate). Đây là LÕI dùng chung, được gọi bởi NTAPP-fix-bug (nguồn file BUGS-*.md, in-place-nocommit) và workflow bug-fix-batch (nguồn Jira, branch-commit); KHÔNG phải lệnh người dùng thường gõ trực tiếp. Chạy: root-cause (superpowers-systematic-debugging) → DD gate (reconstruct v1→v2 khi thiếu DD chạm contract) → ATDD gate (test-first RED→GREEN khi mandatory) → fix tối thiểu → pre-commit 9 rule → verify bậc cao nhất có sẵn → code-review → doc-sync spec. Tôn trọng dual-repo (spec ↔ code). Sử dụng khi một orchestration cần fix đúng một bug đã được localize + phân loại, hoặc khi người dùng chỉ định fix một bug đơn lẻ đã biết unit.'
+---
+
+# Bug-Fix Engine (ceremony-adaptive)
+
+## Overview
+Fix **đúng một bug đã được localize** trên một WBS unit, end-to-end, với **mức ceremony thích ứng** theo tín hiệu (`lane` / `atdd_class` / có chạm contract hay không — `severity` KHÔNG phải trục gate, xem bảng Inputs). Đây là **nguồn sự thật duy nhất** cho "làm sao fix đúng một bug" — cả `NTAPP-fix-bug` và workflow `bug-fix-batch` đều gọi engine này thay vì tự viết lại.
+
+**Nguyên tắc cốt lõi:** gate KHÔNG luôn bật. Bug critical-domain / đổi contract → nghiêm (test-first RED→GREEN + DD reconstruct); bug vặt (express, style thuần) → nhẹ (fix + verify tĩnh). Nhờ đó batch hết over-fix bug nhỏ, còn fix-bug được rigor đúng lúc.
+
+## When to use
+- Một orchestration (NTAPP-fix-bug / bug-fix-batch) đã localize + phân loại một bug và cần **thực thi fix** cho một unit.
+- Người dùng chỉ định fix **một bug đơn lẻ** đã biết chắc unit + file (edge case invoke trực tiếp).
+
+## When NOT to use
+- Chưa localize (chưa biết unit/file) → dùng intake trước: `receive-bug-jira` (Jira) hoặc `NTAPP-fix-bug` step-01 (file `BUGS-*.md`).
+- Muốn gom nhóm N bug fix song song → `receive-bug-jira` + workflow `bug-fix-batch`.
+- Feature mới theo WBS → `slice-loop` / `NTAPP-feature-design`.
+
+## Inputs (caller truyền; engine tự classify lại nếu thiếu)
+| Param | Bắt buộc | Ghi chú |
+|---|---|---|
+| `bug_context` | ✅ | keys/summary/expected/actual/evidence + unit(s) đã localize + files/dirs (+ ảnh nếu có) |
+| `lane` | mặc định | `express` \| `path-b` \| `ad-hoc` — mức ceremony khuyến nghị; thiếu → engine suy từ severity/scope |
+| `atdd_class` | mặc định | `mandatory` (khớp ≥1 trong 5 trigger §5.1) \| `optional`; thiếu → engine classify tại chỗ |
+| `severity` | mặc định | Critical..Low (hoặc Jira `priority` từ nhánh batch) — **chỉ để ordering + suy `lane` khi thiếu**; KHÔNG trực tiếp bật gate nào |
+| `commit_mode` | ✅ | `branch-commit` (commit lên branch trong worktree) \| `in-place-nocommit` (không commit) |
+| `doc_sync_mode` | ✅ | `inline` (doc-sync ngay) \| `deferred` (chỉ emit TODO — orchestration sync serial để tránh tranh ghi spec repo khi fanout) |
+
+**REQUIRED SUB-SKILL:** dùng `superpowers-systematic-debugging` cho root-cause (step-01) trước khi sửa bất kỳ dòng code nào.
+
+## Workflow
+Đọc đầy đủ và tuân theo **`./workflow.md`** (INITIALIZATION + CEREMONY RESOLVER + global rules + pipeline map). Progressive disclosure: đọc **đúng một step file mỗi lần**.

package/skills/NTAPP/.agent/skills/NTAPP-bug-fix-engine/steps/step-01-rootcause-gates.md

@@ -0,0 +1,42 @@
+# Step 01 — Root-cause + DD gate + ATDD gate (quyết định TRƯỚC khi chạm code)
+
+**Persona:** Dev điều tra nguyên nhân + chốt gate cần chạy cho bug này.
+
+**Mục tiêu:** Xác định nguyên nhân gốc, rồi áp CEREMONY RESOLVER để quyết DD gate + ATDD gate ở mức đúng — TRƯỚC khi sửa một dòng code nào.
+
+---
+
+## 1. Root-cause (LUÔN — `superpowers-systematic-debugging`)
+- Đọc kỹ file code đã localize trong `bug_context`. Xác minh giả thuyết nguyên nhân bằng đọc code thật (data flow / state / style cascade), KHÔNG sửa khi chưa chỉ ra được dòng/nguyên nhân.
+- Đối chiếu `expected` vs `actual` + ảnh bug (nếu có). Bug có route/step → reproduce trước khi fix (mượn self-reproduce của `bug-report-jira` nếu cần).
+- Bug UI typography/spacing/màu: tra token chuẩn trong `ds_root/master_token.json` + cách unit khác dùng, để fix về đúng token chung (không chế giá trị mới).
+
+## 2. DD GATE (theo resolver — quyết định version/contract)
+Với unit đã localize chắc (Tier 1/2):
+
+- **DD đã có** (`dd_dir/<unit>_detailed_design.md` tồn tại) → đọc DD, fix cho conform contract/behavior mô tả.
+  - Fix làm code CONFORM DD đang có → **GIỮ nguyên `dd_version`**.
+  - Fix phát hiện DD SAI/THIẾU (DD đang mô tả chính hành vi lỗi) → update mục contract/behavior của vùng bug thành hành vi đúng + **bump `vN→vN+1`** trong DD, đồng bộ header `dd_version` file code.
+  - Unit thuộc slice đã chạy Stage 4/5 → thường đã có DD + story + ATDD → rơi vào nhánh này; tái dùng ATDD/demo slice để verify ở step-02.
+
+- **DD chưa có** (unit CÓ trong WBS nhưng chưa chạy Stage 4 — hay gặp legacy):
+  - Nếu resolver quyết **reconstruct** (fix chạm contract/behavior mô tả bởi DD, HOẶC `commit_mode=branch-commit` mà Rule 3 active) → làm 2 nhịp, KHÔNG bypass:
+    (i) **DD v1 AS-IS:** reconstruct DD từ code HIỆN CÓ, mô tả contract/state/behavior ĐANG CHẠY (dùng lại code THẬT, KHÔNG thiết kế lại) — snapshot trung thực, CÓ THỂ còn hành vi bug. Ưu tiên gọi `/NTAPP-feature-design <unit>` headless (không hỏi HITL); skill chưa symlink → viết DD theo template của nó (đọc code unit + WBS + consumer trong `ripples`). Ghi `dd_dir/<unit>_detailed_design.md` với `dd_version: v1`.
+    (ii) **FIX + bump v2:** sửa mục contract/behavior của VÙNG BUG thành hành vi ĐÚNG (target) mà code sau-fix thoả; bump `dd_version: v2` trong DD + header code. Delta v1→v2 = audit trail (bug as-is → đúng ra sao).
+  - Nếu resolver quyết **nhẹ** (fix internal-only + `in-place-nocommit`, không đụng contract) → KHÔNG reconstruct full: giữ header `id:`+`dd_version:` nhất quán, ghi flag "DD thiếu, fix internal-only, chưa reconstruct" vào report cho user quyết sau.
+
+- **Tier 3/4 chưa định vị** → KHÔNG viết DD giả, KHÔNG đoán unit → đẩy `needs-investigation` + báo cần bổ sung route/file. DỪNG bug này (report escalate).
+
+- **WBS gap** (unit chắc nhưng không có dòng nào trong `wbs`): id đã có trong header code → thêm 1 dòng đối chiếu DRAFT (copy đúng id + mô tả 1 dòng + container), đánh dấu review ở close-out; phải đặt tên unit mới → escalate `/ntapp-architecture-design`, KHÔNG commit id tự chế.
+
+## 3. ATDD GATE (theo resolver — chống regression mien nhạy cảm)
+- `atdd_class` đã có (caller gán) → dùng; chưa có → classify tại chỗ (5 trigger §5.1, xem CEREMONY RESOLVER).
+- **`mandatory`** → BẮT BUỘC test-first, đúng thứ tự (test TRƯỚC fix):
+  (a) **Framework guard:** detect config test của module/stack (FE: `playwright.config.*`/`cypress.config.*`; BE: `conftest.py`/`src/test/`/`go.mod` + `*_test.go`/`.rspec`). THIẾU → gọi `/bmad-testarch-framework` scaffold TRƯỚC (nếu không, `bmad-testarch-atdd` preflight HALT im lặng trong headless).
+  (b) Viết 1 **regression test** tái hiện bug qua `/bmad-testarch-atdd` (story = `<unit>`) → test PHẢI FAIL (RED) trước khi fix. Unit thuộc slice đã có ATDD → THÊM/MỞ RỘNG case, KHÔNG viết lại.
+  (c) Ghi nhớ: fix ở step-02 phải làm test XANH (GREEN). Critical-domain thiếu test phụ → **BLOCKER** (khác DD: DD reconstruct được, test mandatory thì KHÔNG bypass).
+- **`optional`** → khuyến nghị viết regression test, KHÔNG chặn.
+
+---
+
+**Next:** Read fully and follow `./steps/step-02-fix-verify-review.md`

package/skills/NTAPP/.agent/skills/NTAPP-bug-fix-engine/steps/step-02-fix-verify-review.md

@@ -0,0 +1,46 @@
+# Step 02 — Fix + pre-commit + verify + code-review
+
+**Persona:** Dev sửa lỗi tối thiểu, đúng nguyên nhân đã chốt ở step-01.
+
+**Mục tiêu:** Sửa code cho đúng root-cause, giữ đúng pre-commit tuỳ `commit_mode`, verify ở bậc cao nhất có sẵn, review theo `lane`.
+
+---
+
+## 1. Fix code (tối thiểu, đúng nguyên nhân)
+- Sửa **tối thiểu, đúng nguyên nhân** (R4 — không refactor ngoài phạm vi bug). Fix đúng blast radius đã localize (R2).
+- Chạm hot node → kiểm consumer trong `ripples` không vỡ (giữ signature/contract). Phát hiện phải chạm file NGOÀI blast radius → DỪNG, ghi ESCALATE, KHÔNG lan sang unit khác.
+- **ATDD `mandatory`** (từ step-01): sửa đến khi regression test XANH (GREEN). Đây là test-first: RED (step-01) → GREEN (đây).
+- Đa file/đa repo: một bug trải nhiều điểm → sửa hết các điểm liên quan trong đúng (các) repo sở hữu unit.
+
+## 2. Pre-commit compliance (theo resolver)
+Áp Rule liên quan của pre-commit 9-rule cho vùng code sửa (dù có commit hay không — để commit sau của user không vỡ):
+- **Rule 1** — header `id: <unit> | dd_version: vN` trong 10 dòng đầu; `vN` khớp `dd_version` của DD SAU-FIX (reconstruct case: DD đã bump v2 ở step-01 → header code phải `dd_version: v2`).
+- **Rule 4/6/9 (UI)** — không hardcode color hex/px/font-family (dùng design token); UI file có `ui_schema` tương ứng; KHÔNG emoji unicode (import icon từ `stack-profile.icon_library`).
+- `commit_mode=branch-commit` → Rule 2/3 phải PASS hợp lệ (unit có trong WBS + DD có/đã reconstruct). `SKIP_PRECOMMIT=1` CHỈ cho diện escalate (Tier 3/4 không viết được DD, hoặc WBS gap phải đặt id mới) — commit trên branch để không mất công + gắn cờ rõ trong report.
+- `commit_mode=in-place-nocommit` → không commit ở đây; chỉ đảm bảo header nhất quán để hook fire đúng khi user commit sau.
+
+## 3. Verify (bậc cao nhất có sẵn — ghi trung thực)
+Theo thứ tự ưu tiên, dừng ở bậc cao nhất khả thi:
+1. **ATDD/test liên quan** → chạy runner lọc theo unit. Unit thuộc slice có `demoable` + AC trong story → chạy ATDD/demo slice đó (bao phủ hành vi tốt nhất). Pass = chắc nhất.
+2. **Không test nhưng có đường chạy/build** → build + smoke; quan sát không còn lỗi bug gốc.
+3. **UI-style thuần** (không có test tự động) → verify bằng đọc lại code so token + mô tả; ghi rõ **cần verify trực quan thủ công** (so ảnh bug). KHÔNG tự nhận đã verify visual khi chưa chạy app.
+4. **Không chạy được test trong môi trường** → ghi "verify: static-only / chưa verify tự động" + nêu rủi ro.
+
+**GATE:** ATDD `mandatory` mà không có regression test XANH kèm theo → **BLOCKER**: KHÔNG tính là fixed, ghi vào report, KHÔNG commit.
+
+## 4. Code-review (INLINE self-review — theo resolver)
+**KHÔNG gọi `/bmad-code-review`**: skill đó có chuỗi HALT "wait-for-human" + persist bám theo story file → trong headless/fanout sẽ treo hoặc ghi finding vào hư vô. Engine là fresh-context nên tự review trực tiếp, chắc chắn hơn.
+
+Self-review diff của lần fix này theo rubric gọn:
+1. **Correctness:** bug gốc thực sự được xử lý (không che triệu chứng); fix conform DD (step-01).
+2. **Blast radius:** diff CHỈ chạm file đã localize; rò rỉ file ngoài blast radius = dấu hiệu localize/grouping sót → ESCALATE (không tự sửa lan).
+3. **Contract/ripples:** chạm hot node → GIỮ signature/shape response; consumer trong `ripples` không vỡ.
+4. **Regression:** không phá behavior lân cận; có ATDD/test liên quan (step-01) → đối chiếu.
+5. **Rule 4/6/9** (khi chạm `.tsx/.jsx/.css/.scss`): không hardcode token màu/px/font, không emoji.
+
+- `lane≠express` → self-review **đầy đủ** cả 5 mục. `lane=express` (trivial) → self-review **nhanh** (tập trung 1/5).
+- Sửa NGAY finding tầm thường. Finding còn lại + ESCALATE → **LUÔN đưa vào fix-report** (step-03). Orchestration lo persist ra file (fanout) hay in report (interactive) — engine KHÔNG tự ghi file review.
+
+---
+
+**Next:** Read fully and follow `./steps/step-03-close.md`

package/skills/NTAPP/.agent/skills/NTAPP-bug-fix-engine/steps/step-03-close.md

@@ -0,0 +1,46 @@
+# Step 03 — Doc-sync + commit + fix-report (terminal)
+
+**Persona:** Người giữ spec khớp code + đóng gói kết quả trả orchestration.
+
+**Mục tiêu:** Đồng bộ tài liệu spec đã lệch (theo `doc_sync_mode`), commit theo `commit_mode`, xuất **fix-report có cấu trúc**.
+
+---
+
+## 1. Doc-sync (theo `doc_sync_mode`)
+- `doc_sync_mode=inline` (tuần tự — vd NTAPP-fix-bug) → chạy doc-sync ngay.
+- `doc_sync_mode=deferred` (fanout song song — vd bug-fix-batch) → **KHÔNG ghi spec repo ở đây** (tránh tranh ghi giữa các fix song song); chỉ **emit TODO** trong report (unit + doc ứng viên + bản chất thay đổi) để node serial của orchestration sync sau.
+
+Khi `inline`, xác định doc ứng viên theo bản chất thay đổi code (chỉ sửa khi **thực sự lệch**, surgical — R3):
+
+| Loại thay đổi code | Doc cần đối chiếu |
+|---|---|
+| Behavior / luồng xử lý | `dd_dir/<unit>_detailed_design.md`; `techspec_dir/*<unit>*` |
+| API contract (path/method/request/response) | techspec + `dd_dir/<unit>_detailed_design.md` (mục API) |
+| Props / cấu trúc component UI, state | `dd_dir/<unit>_detailed_design.md`; `ui_schema_dir/ui_schema_<unit>.json`; `build_verify_dir/<unit>.md` |
+| Token / component design-system (NEW/MODIFIED) | `ds_root/master_token.json`, `ds_root/components_metadata.json`, `ds_root/feature_deltas/<unit>/` |
+| Tiêu chí demo / acceptance của slice | `slice_files[]` từ `slice_paths.py --resolve <SLICE>` (**không** glob `slices_dir/<SLICE>*.md` — `SLICE-2` bắt luôn `SLICE-20/21/24`); story file ở `build_verify_dir/` |
+
+- **Bug UI-style thuần** (chỉ chỉnh token/spacing về đúng chuẩn, không đổi behavior/contract/props) → thường **không** cần sửa doc; chỉ cập nhật nếu doc/ui_schema ghi sai giá trị token. Ghi "không có doc lệch" nếu vậy.
+- **Đổi behavior/contract/props** → sửa đúng đoạn doc mô tả sai cho khớp code mới (surgical, không viết lại toàn bộ).
+- **`*_detailed_design.md` đổi bản chất** → bump `dd_version` (đã làm ở step-01 nếu reconstruct/đổi contract); đảm bảo header code khớp.
+- **`ui_schema` JSON** → chỉnh field lệch (binding/props/token ref) cho khớp component mới.
+
+## 2. Commit (theo `commit_mode`)
+- `branch-commit` → verify pass (ATDD `mandatory` phải XANH) → `git add -A && git commit` trên `<branch>` trong worktree. **KHÔNG push. KHÔNG merge vào main.**
+- `in-place-nocommit` → **KHÔNG commit**; để orchestration/user review. (Việc flip status file / báo cáo cuối do caller lo.)
+
+## 3. Fix-report có cấu trúc (trả orchestration)
+Xuất block gọn cho caller tiêu thụ:
+- **unit** + **bug keys/id**
+- **root-cause** (1-2 dòng)
+- **files đã sửa** (repo/path)
+- **ceremony đã áp**: lane / atdd_class / DD action (giữ|bump vN→vN+1|reconstruct v1→v2|flag) / code-review (có|self)
+- **dd_version delta** (nếu có)
+- **verify-level**: atdd-green | build-smoke | static-only | BLOCKER + chi tiết
+- **review findings còn lại**
+- **doc-sync**: đã sync (liệt kê doc) | deferred-TODO (liệt kê doc ứng viên) | không lệch
+- **BLOCKER / ESCALATE** (nếu có): mandatory-ATDD thiếu test, Tier 3/4, WBS gap cần đặt id mới, file ngoài blast radius...
+
+---
+
+**DONE.** Engine dừng sau report. Không HITL, không hành động ngoài phạm vi bug (orchestration quyết bước tiếp: commit/merge/flip-status/demo).

package/skills/NTAPP/.agent/skills/NTAPP-bug-fix-engine/workflow.md

@@ -0,0 +1,100 @@
+# Bug-Fix Engine Workflow (ceremony-adaptive)
+
+**Goal:** Fix đúng **một bug đã localize** trên một WBS unit, end-to-end, với mức ceremony vặn theo tín hiệu. Trả về **fix-report có cấu trúc** cho orchestration gọi nó.
+
+**Your Role:** Bạn là **engine per-bug** — được gọi bởi một orchestration (NTAPP-fix-bug / bug-fix-batch). KHÔNG tự localize (caller đã làm), KHÔNG tự quyết concurrency/merge (orchestration lo). Chỉ nhận `bug_context` + tín hiệu, chạy 3 step, xuất report.
+
+**Ngôn ngữ:** trả lời & viết report bằng **tiếng Việt** (thuật ngữ kỹ thuật giữ tiếng Anh).
+
+---
+
+## WORKFLOW ARCHITECTURE — Progressive disclosure
+
+- File này giữ KHUNG (INITIALIZATION + CEREMONY RESOLVER + global rules + pipeline map). Chi tiết thực thi nằm TRONG từng step file.
+- ⛔ Đọc ĐÚNG MỘT step mỗi lần. Hoàn tất step hiện tại RỒI mới đọc step kế. State chuyển qua code + report, không qua giữ instruction trong context.
+
+---
+
+## INITIALIZATION (Configuration Resolution)
+
+Caller thường đã resolve path và truyền qua `bug_context`. Nếu invoke standalone, resolve tối thiểu:
+
+### Bước 0 — `{spec_repo_root}`
+Walk up từ cwd: thấy `_bmad/` → `{spec_repo_root}`; else thấy `NTAPP-output/` → `{spec_repo_root}`; else fallback `cwd` + log warning.
+
+### Bước 1 — Code repo(s)
+Dual-repo: code KHÔNG nằm trong spec repo. Resolve repo sở hữu unit từ (theo thứ tự): (a) field repo trong `bug_context`; (b) `NTAPP-output/Stage_5_Build_Verify/bug-batches/_unit-path-map.yaml` (`containers[].repo`); (c) additional working dirs đang mở / sibling dirs chứa source (`src/`, `package.json`, `pom.xml`, `build.gradle`, `go.mod`, ...). **KHÔNG hardcode tên repo** — luôn resolve runtime.
+
+### Bước 2 — Paths chuẩn (spec repo)
+| Biến | Giá trị |
+|---|---|
+| `wbs` | `{spec_repo_root}/NTAPP-output/Stage_2_Architecture/project_wbs.md` |
+| `techspec_dir` | `{spec_repo_root}/NTAPP-output/Stage_3_Specs/techspec/` |
+| `dd_dir` | `{spec_repo_root}/NTAPP-output/Stage_4_Design/detailed_design/` |
+| `ui_schema_dir` | `{spec_repo_root}/NTAPP-output/Stage_4_Design/ui_schema/` |
+| `ds_root` | `{spec_repo_root}/NTAPP-output/design-system/` |
+| `build_verify_dir` | `{spec_repo_root}/NTAPP-output/Stage_5_Build_Verify/` |
+| `slices_dir` | helper trả về (`slices_dir`); mặc định `{spec_repo_root}/NTAPP-output/Stage_2_Architecture/slices/` |
+| `date` | ngày hệ thống, `YYYY-MM-DD` |
+
+> ⚠️ **`slices_dir` KHÔNG ghép tay — gọi helper:**
+>
+> ```
+> python3 {project-root}/hooks/lib/slice_paths.py --resolve <SLICE-ID> --json
+> ```
+> *(Windows: dò `py -3` → `python3` → `python`.)* Trả về `slices_dir`, `bugs_dir`, `assets_dir`, `slice_files[]`, `bug_files[]`, `warnings[]`.
+>
+> Bảng này từng ghi `Stage_5_Build_Verify/slices/` — **thư mục không tồn tại**; slice thật ở `Stage_2_Architecture/slices/`. Helper còn khớp mã slice theo **ranh giới** (`SLICE-2` không bắt `SLICE-20`) và chuẩn hoá zero-pad (`SLICE-06` ↔ `SLICE-6`), đồng thời nhận cả bố cục phẳng lẫn thư mục feature.
+>
+> **Mã thoát:** `0` = tra được (danh sách rỗng nghĩa là *thật sự không có*); `3` = **không tra được**, DỪNG và đọc `warnings`; `2` = mã slice sai dạng.
+
+---
+
+## CEREMONY RESOLVER (bất biến — trái tim của engine)
+
+Trước khi chạm code, quyết mức ceremony từ tín hiệu. Thiếu tín hiệu → classify tại chỗ (xem note). **Mặc định an toàn: mơ hồ → nghiêng NẶNG; critical-domain LUÔN test-first bất kể `lane`.**
+
+> **`severity` KHÔNG phải trục gate** — không dòng nào dưới đây key trên nó; chỉ dùng để sắp thứ tự fix (Critical→Low) + suy `lane` khi thiếu. Đừng nhầm `severity=Critical` với **critical-domain** (trigger **B1** của `atdd_class`: auth/tiền/RBAC/PII) — bug Critical-severity nhưng UI-style thuần vẫn có thể `express`.
+
+| Gate | Bật đầy đủ khi | Nhẹ / skip khi |
+|---|---|---|
+| **root-cause** | **LUÔN** (superpowers-systematic-debugging) | — |
+| **DD gate** | DD thiếu **và** (fix chạm contract/behavior mô tả bởi DD **hoặc** `commit_mode=branch-commit` mà Rule 3 đang active) → **reconstruct DD v1 as-is → fix → bump v2**. DD có + fix đổi contract → update DD + bump version | DD có + fix conform → **giữ version**. DD thiếu + fix internal-only + `in-place-nocommit` → chỉ giữ header nhất quán + flag report (KHÔNG reconstruct full) |
+| **ATDD gate** | `atdd_class=mandatory` → framework guard + **test-first RED→GREEN** (critical-domain thiếu test = **BLOCKER**, KHÔNG bypass) | `atdd_class=optional` → khuyến nghị regression test, **KHÔNG chặn commit** |
+| **verify** | LUÔN, ở **bậc cao nhất có sẵn**: slice ATDD/demo (nếu unit thuộc slice có test) → per-unit test/build → static. Ghi TRUNG THỰC bậc đã verify | (không hard-require slice) |
+| **code-review** | INLINE self-review theo rubric (KHÔNG gọi `/bmad-code-review`: skill đó có chuỗi HALT wait-for-human + persist theo story → **treo/mất finding trong headless & fanout**). `lane≠express` → self-review đầy đủ | `lane=express` → self-review nhanh. Finding LUÔN xuất trong fix-report; orchestration lo persist |
+| **pre-commit** | `commit_mode=branch-commit` → enforce 9 rule (`SKIP_PRECOMMIT` CHỈ cho diện escalate) | `commit_mode=in-place-nocommit` → giữ header `id:`+`dd_version:` nhất quán để commit sau của user pass Rule 1 |
+
+**Classify tại chỗ nếu thiếu:**
+- `atdd_class`: đối chiếu 5 trigger Mandatory ATDD (canonical `docs/Process/Manual_phase_1.md` §5.1) — A1 cross-system · A2 multi-actor/stateful · A3 async/resilience · B1 critical-domain (auth/tiền/RBAC/PII) · B2 destructive. Match ≥1 → `mandatory`.
+- `lane`: suy từ severity + scope (trivial + không đổi contract → express; unit có DD, chỉ fix/refactor → path-b; còn lại → ad-hoc).
+
+**Escalate (KHÔNG bịa):** unit chưa localize chắc (Tier 3/4) → `needs-investigation`, KHÔNG bịa DD / KHÔNG đoán unit. WBS gap (unit chắc nhưng không có dòng nào trong `project_wbs.md`) → KHÔNG bịa id mới: id có sẵn trong header → thêm dòng đối chiếu DRAFT; phải đặt tên mới → escalate `/ntapp-architecture-design`.
+
+---
+
+## GLOBAL RULES (mọi step)
+
+- **R1 — Root-cause trước khi fix:** tuân `superpowers-systematic-debugging`. Cấm fix mò triệu chứng khi chưa chỉ ra nguyên nhân.
+- **R2 — Blast radius:** fix đúng vùng đã localize; chạm hot node → kiểm consumer trong `ripples` không vỡ (giữ signature/contract). Phải chạm file NGOÀI blast radius / của unit khác → DỪNG, ghi ESCALATE (dấu hiệu localize/grouping thiếu), KHÔNG tự lan sang unit khác.
+- **R3 — Code là nguồn sự thật sau fix:** doc-sync chỉnh doc theo code mới (surgical); DD đổi bản chất → bump `dd_version` + đồng bộ header code.
+- **R4 — Không đổi hành vi ngoài phạm vi bug** (Simplicity First — không refactor thừa).
+- **R5 — Secret:** không in/log/commit secret.
+- ⛔ Đọc đúng một step file mỗi lần.
+
+---
+
+## PIPELINE MAP (neo thường trực)
+
+| # | Step file | Mục tiêu |
+|---|---|---|
+| 01 | steps/step-01-rootcause-gates.md | root-cause[luôn] → DD gate[dial] → ATDD gate[dial] (quyết định TRƯỚC khi chạm code) |
+| 02 | steps/step-02-fix-verify-review.md | fix tối thiểu → pre-commit[dial] → verify[bậc cao nhất] → code-review[dial] |
+| 03 | steps/step-03-close.md | doc-sync[inline\|deferred] → commit[commit_mode] → xuất fix-report |
+
+Chuỗi: **01 → 02 → 03 (terminal)**. Không HITL gate trong engine (gate nằm ở orchestration).
+
+---
+
+## LAUNCH
+Sau INITIALIZATION + CEREMONY RESOLVER (chốt mức mỗi gate): **Next:** Read fully and follow `./steps/step-01-rootcause-gates.md`