ai-developer-skill-os 9.1.1 → 9.1.2

package/.agents/skills/qk-context-loader/SKILL.md

@@ -168,6 +168,86 @@ Không lưu:
 
 
 
+### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
+- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
+  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
+  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
+
+---
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Pattern / Architecture (vd: sơ đồ phụ thuộc mô-đun, biểu đồ ngữ cảnh O(1)).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Quyết định Architecture hoặc Pattern quan trọng khi ánh xạ dependency.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Cache đồ thị ngữ cảnh tạm thời của một lệnh tìm kiếm.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+
+
+
 ### Pre-flight Retrieve (Trước khi thực thi)
 - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
   bắt buộc tra cứu:

package/.agents/skills/qk-data-engineer/SKILL.md

@@ -0,0 +1,474 @@
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-data-engineer
+version: 9.1.0
+status: stable
+description: "Universal Data Engineering Skill — Tự động thích nghi với project context, áp dụng các best practices (Idempotency, Data Quality, Lineage, Security) không giới hạn tech stack."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V9: Classification ─────────────────────────────────────
+type: capability
+
+intent:
+  - data-pipeline
+  - data-modeling
+  - data-quality
+  - etl-optimization
+
+complexity:
+  level: high
+  criteria:
+    files_affected: "1-15"
+    has_behavior_change: true
+    has_external_dependency: true
+    has_breaking_change: false
+
+triggers:
+  - "data engineer"
+  - "etl"
+  - "elt"
+  - "data pipeline"
+  - "dbt model"
+  - "spark job"
+  - "airflow dag"
+  - "data quality gate"
+  - "medallion"
+  - "iceberg"
+
+selection:
+  priority: high
+  confidence_threshold: 0.85
+
+# ── V8: References ─────────────────────────────────────────
+workflow: feature-delivery
+
+rules:
+  - global
+  - coding
+  - safety
+
+tools:
+  - filesystem
+  - terminal
+
+related_skills:
+  - qk-data-lifecycle
+  - qk-db-optimizer
+  - qk-validation-gate
+
+knowledge_scope:
+  owns:
+    - data-pipeline-architecture
+    - data-contracts
+    - data-quality-gate
+    - incremental-processing
+  references:
+    - architecture
+    - security
+    - performance
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: feature
+
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
+execution_mode: deterministic
+cost: high
+latency: medium
+risk: high
+side_effects: edit_files
+produces: [code, schema, report]
+consumes:
+  - user-request
+  - project-source-code
+  - project-config
+  - project-tests
+  - project-documentation
+  - project-memory
+
+token_budget:
+  max_files_read: 20
+  max_lines_per_read: 200
+  max_shell_commands: 10
+  stop_early: true
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-data-engineer — Universal Data Engineer
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## Memory Workflow (Universal Project Knowledge V1 Protocol)
+
+### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
+- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
+  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
+  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
+
+---
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture (vd: Lakehouse layout, Medallion structure, storage prefixes)
+  - Hard Bug (vd: API pagination loss, composite keys mismatch, partition pruning bug)
+  - Convention (vd: naming snake_case, schema compatibility rules)
+  - Pattern (vd: Ingestion template, Quality Gate assertions)
+  - Tech Debt Pattern
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**. Không được xem Memory là Source of Truth. Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn (vd: lỗi sort watermark khi nạp gia tăng).
+  - Pattern làm việc lặp lại trong dự án (vd: template contract JSON, schema DDL, DAG wrapper).
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức, lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua `/learn` hoặc `qk-project-memory`.
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
+```
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data / raw sample payloads.
+- Output của một lần chạy test/scan/quality gate tạm thời.
+- Lỗi nhỏ cú pháp SQL/Python chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+
+## Source-of-Truth Hierarchy
+
+Khi có sự mâu thuẫn thông tin giữa các nguồn, AI **BẮT BUỘC** giải quyết theo thứ tự ưu tiên giảm dần:
+
+1. **Explicit user instruction** (Chỉ thị trực tiếp từ người dùng trong phiên làm việc)
+2. **Current production / project configuration** (Cấu hình thực tế đang chạy: YAML, JSON, env)
+3. **Current source code + tests** (Mã nguồn và bài kiểm thử đang có trong repository)
+4. **Current project documentation** (Tài liệu đặc tả, bàn giao kỹ thuật cập nhật của dự án)
+5. **Approved project knowledge / memory** (`.ai-local/knowledge/index.yaml`)
+6. **Generic engineering best practices** (Tiêu chuẩn kỹ thuật chung của ngành)
+7. **Model inference** (Suy luận ngầm định của mô hình AI)
+
+> ⚠️ *Never let a lower-priority source override a higher-priority source.*
+
+---
+
+## Preconditions
+
+### Required for Implementation
+- [ ] Xác định được mục tiêu hoặc phạm vi task (New pipeline, debug, modify, optimize, v.v.).
+- [ ] Đã thực hiện Pre-flight Inspection phát hiện Tech Stack, Architecture và Conventions của dự án.
+
+### Required When Applicable
+- [ ] Data Contract / Schema DDL (Bắt buộc khi implement/modify pipeline; Không bắt buộc nếu task là discovery/tạo contract mới).
+- [ ] Business Grain & Primary Key (Khi thiết kế Data Model hoặc Incremental pipeline).
+- [ ] Incremental Cursor / Watermark strategy (Khi xây dựng luồng nạp gia tăng).
+
+---
+
+## Scope & Core Principles
+
+### Core Principles (Thứ tự ưu tiên cốt lõi)
+1. **Correctness & Data Integrity**: Dữ liệu phải phản ánh chính xác nghiệp vụ. Không đánh đổi tính đúng đắn để lấy tốc độ.
+2. **Idempotency & Fault Tolerance**: Mọi pipeline phải an toàn khi chạy lại nhiều lần (re-run không nhân bản dữ liệu, không sinh rác).
+3. **Data Quality**: Luôn có chốt chặn kiểm tra tự động trước khi publish dữ liệu.
+4. **Schema & Contract Discipline**: Schema and Data Contract are explicit compatibility boundaries and must be versioned when changed.
+5. **Observability & Lineage**: Mọi bản ghi phải truy vết được nguồn gốc theo cơ chế lineage của dự án.
+6. **Security & Privacy**: Apply the project's approved privacy/protection mechanism (masking, tokenization, encryption); never expose sensitive data or credentials.
+7. **Performance & Cost**: Tối ưu partitioning, clustering, query plan nhưng không phá vỡ tính đúng đắn.
+8. **Maintainability & Simplicity**: Code tường minh, dễ đọc và dễ bàn giao.
+
+### This skill does:
+- ✅ Tự động thích nghi với hệ sinh thái dữ liệu của dự án (Spark, dbt, Airflow, Dagster, Snowflake, Iceberg, BigQuery...).
+- ✅ Thiết kế và xây dựng Data Pipelines (ETL/ELT) an toàn, idempotent.
+- ✅ Thiết kế Data Modeling (Medallion, Star Schema, OBT) phù hợp workload.
+- ✅ Quản lý Data Contracts, Schema Evolution và phát hiện Breaking Changes.
+- ✅ Cài đặt Data Quality Gates với Severity Matrix (CRITICAL, ERROR, WARNING, INFO).
+- ✅ Tối ưu hiệu năng truy vấn, compaction, layout và tài nguyên compute.
+- ✅ Debugging và điều tra sự cố dữ liệu (Lineage, Snapshot, PIR).
+
+### This skill does NOT:
+- ❌ Tự ý chọn tech stack mới nếu dự án chưa dùng hoặc chưa có yêu cầu.
+- ❌ Sửa ngầm logic tính toán hoặc schema production mà không có Impact Analysis.
+- ❌ Bỏ qua Data Quality Gate chỉ để pipeline "chạy xanh".
+- ❌ Tuyên bố "Production-Ready" khi chỉ mới vượt qua unit test ở môi trường local.
+
+---
+
+## Rules & Decision Rules
+
+### Rules Bắt Buộc
+- ❌ **No Stack Hallucination**: Không tự chọn dbt/Spark/Airflow nếu project chưa sử dụng.
+- ❌ **No Schema Guessing**: Schema từ Data Contract/DDL là Source of Truth, không đoán mò từ sample JSON.
+- ❌ **Authoritative Path & Location Builder**: Ưu tiên sử dụng cơ chế sinh đường dẫn/vị trí lưu trữ chính thức của dự án. Tuyệt đối không tự bịa hoặc nối chuỗi path thủ công khi dự án đã cung cấp module chuẩn.
+- ❌ **Preserve Authoritative Lineage**: Tuân thủ hoặc triển khai cơ chế lineage chuẩn của dự án (OpenLineage, metadata columns, audit tables). Nếu dự án chưa có, đề xuất chiến lược lineage tối thiểu phù hợp với nền tảng.
+- ❌ **No Silent Behavior Mutation**: Thay đổi nghiệp vụ phải kèm migration strategy và impact analysis.
+
+### Decision Rules
+- **IF** project has existing orchestration framework **→ USE IT**.
+- **IF** project has existing Data Contracts **→ CONTRACT IS SOURCE OF TRUTH**.
+- **IF** task requires incremental processing **→** Xác định Watermark & Dedup; **KHÔNG** sort theo watermark khi phân trang API.
+- **IF** transformation has both Deduplication & PII Masking **→** Áp dụng các phép biến đổi theo yêu cầu hợp đồng và quy tắc bảo mật; khi cần cả hai, **BẮT BUỘC** duy trì thứ tự phụ thuộc (khử trùng lặp trước khi che thông tin để không làm mất khóa định danh).
+- **IF** architecture choice materially affects data correctness, security, cost, downstream compatibility, or production architecture **→ BLOCKED / request decision**.
+- **ELSE** (Quyết định kiến trúc nhỏ/không gây rủi ro phá vỡ) **→** Chọn phương án ít gây bất ngờ nhất, đồng bộ với convention dự án và ghi rõ lý do (rationale).
+- **IF** requested change can break downstream consumers **→** Thực hiện Impact Analysis trước khi thay đổi.
+
+---
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Pre-flight Stack, Convention & Contract Discovery | Never |
+| P2 | Schema Validation & Breaking Change Check | Never |
+| P3 | Idempotency & Re-run Safety Design | Never |
+| P4 | Data Quality Assertions (Row integrity, required fields, key uniqueness) | Never |
+| P5 | Security & Privacy Protections Applied | Never |
+| P6 | Layout Tuning (Partitioning/Clustering/Compaction) | When applicable |
+
+---
+
+## Execution Backbone & Workflow Router
+
+### Execution Backbone
+Mọi yêu cầu Data Engineering đều được thực thi theo chuỗi xử lý bất biến sau:
+
+```text
+USER REQUEST
+    ↓
+TASK CLASSIFICATION
+    ↓
+PROJECT CONTEXT (Pre-flight Inspection)
+    ↓
+SOURCE-OF-TRUTH RESOLUTION
+    ↓
+RULE RESOLUTION
+    ↓
+WORKFLOW ROUTER
+    ↓
+COMMON GATES (Discover ➔ Design ➔ Impact Analysis ➔ Implement ➔ Test ➔ QA ➔ Verify ➔ Report)
+```
+
+---
+
+### Workflow Router
+
+Khi phân loại xong task, AI điều hướng vào workflow chuyên biệt:
+
+#### 1. `NEW_PIPELINE` / `etl`
+1. **Discover**: Đọc source schema, stack, existing storage conventions.
+2. **Design**: Xác định source, target, partitioning, load strategy (overwrite_partition, upsert, append).
+3. **Contract**: Tạo hoặc cập nhật Data Contract (fields, types, nullability, PII).
+4. **Implement**: Viết transformation (bảo toàn thứ tự dedup/masking) và bảo đảm Idempotency.
+5. **Quality & Test**: Khai báo assertions và viết unit tests.
+6. **Verify**: Chạy tests, đánh giá trạng thái xác minh.
+
+#### 2. `MODIFY_PIPELINE`
+1. **Inspect**: Đọc code hiện tại, DAG dependencies, configs và tests liên quan.
+2. **Impact Analysis**: Xác định downstream tables, views, dashboards bị ảnh hưởng.
+3. **Compatibility**: Kiểm tra breaking changes đối với schema hiện hữu.
+4. **Implement**: Áp dụng thay đổi tối thiểu, cập nhật contracts & unit tests.
+5. **Quality Gate**: Chạy lại toàn bộ test suite để chống regression.
+
+#### 3. `DEBUG` / `INCIDENT`
+1. **Reproduce**: Tái hiện lỗi với payload hoặc điều kiện lỗi.
+2. **Isolate**: Xác định tầng lỗi (Ingest, Staging, Transform, Quality Gate).
+3. **Inspect**: Tra cứu logs, lineage, snapshot metadata, raw landing payload.
+4. **Root Cause**: Phân tích nguyên nhân gốc rễ (pagination drift, timezone, null pointer).
+5. **Fix & Regression Test**: Sửa lỗi phạm vi tối thiểu, bổ sung regression test và báo cáo PIR.
+
+#### 4. `DATA_MODELING`
+1. **Query Patterns**: Phân tích nhu cầu đọc và SLA của consumer/dashboard.
+2. **Paradigm**: Chọn mô hình phù hợp (Medallion, Star Schema, OBT, Data Vault).
+3. **Grain & Keys**: Định nghĩa Primary Key, Business Key, Foreign Keys và Partitioning key.
+4. **Contract & DDL**: Sinh contract và DDL tường minh.
+
+#### 5. `DATA_QUALITY`
+1. **Asset Profiling**: Liệt kê các bảng và trường cần giám sát.
+2. **Severity Matrix**: CRITICAL (dừng pipeline), ERROR (chặn publish), WARNING (alert), INFO (log metric).
+3. **Assertions**: Cài đặt kiểm tra toàn vẹn dòng (row integrity), trường bắt buộc (not_null), khóa duy nhất (unique), và mở rộng freshness/referential/consistency.
+
+#### 6. `SCHEMA_EVOLUTION`
+1. **Version Diff**: So sánh Schema V_Old vs V_New.
+2. **Classify**: Phân loại Backward Compatible vs Breaking Change.
+3. **Migration Plan**: Viết migration script, xử lý default values và nâng `contract_version`.
+4. **Downstream Validation**: Kiểm tra tính tương thích của views/queries.
+
+#### 7. `BACKFILL` / `REPLAY`
+1. **Scope & Window**: Xác định time window (from_date ➔ to_date) và partitions mục tiêu.
+2. **Isolation**: Dùng partition replacement hoặc atomic merge để không ảnh hưởng dữ liệu đang vận hành.
+3. **Reconcile**: Đối chiếu tổng số dòng và giá trị metric trước/sau backfill.
+
+#### 8. `OPTIMIZE`
+1. **Profile**: Đo thời gian chạy, bytes scanned, memory skew, partition layout.
+2. **Bottlenecks**: Tìm full-table scans, shuffle spills, small files problem.
+3. **Tune**: Rewrite queries (pushdown filters), optimize layout (compaction, Z-Order), tune executor configs.
+4. **Verify Correctness**: Đảm bảo kết quả dữ liệu TRƯỚC và SAU tối ưu hoàn toàn trùng khớp.
+
+---
+
+## Output Format
+
+```markdown
+🔧 Data Engineer Task Summary
+─────────────────────────────────────────────────
+Scope:          [Mô tả ngắn gọn phạm vi: ETL / Debug / Quality Gate / Modeling / Optimize]
+Tech Stack:     [Ecosystem & công cụ đã detect/sử dụng]
+Target Tables:  [Danh sách bảng/datasets liên quan]
+
+📋 Architecture & Assumptions:
+  - Architecture:  [Medallion / Star Schema / OBT / Staging-Mart]
+  - Load Strategy: [Overwrite Partition / Upsert / Append]
+  - Assumptions:   [Các giả định kỹ thuật & nghiệp vụ đã áp dụng]
+
+Changes Applied:
+  ✅ [Action 1]: [Chi tiết những gì đã làm, file đã sửa/tạo]
+  ✅ [Action 2]: [Chi tiết về xử lý logic / contract / transform]
+
+📊 Data Integrity & Quality:
+  - Idempotency:   [Cơ chế đảm bảo chạy lại an toàn]
+  - Quality Gate:  [Các assertions đã khai: row integrity, required fields, unique, freshness, referential]
+  - Lineage:       [Cơ chế lineage áp dụng: OpenLineage / audit columns / metadata]
+
+✅ Verification Status:
+  - Unit Tests:    [Pass / N/A / X tests run]
+  - Quality Gate:  [Passed / Configured]
+  - Environment:   [Local Unit Verified / Real Infra Pending]
+
+⚠️ Risks, Trade-offs & Next Steps:
+  - [Các lưu ý về performance, schema compatibility hoặc việc cần test trên cụm thật]
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Pipeline/Model/Fix implemented, verified, QA passed | All checks passed |
+| PARTIAL | Code done but verification on real infra is pending | Needs live cluster run |
+| BLOCKED | Required information remains unavailable after reasonable project inspection | Missing critical specifications |
+| FAILED | Quality gate failed, breaking change without migration | Security/Integrity violation |
+
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Stack detected, contract exists, clear source-target mapping | Implement end-to-end |
+| MEDIUM | Stack clear but contract or grain partially undefined | State assumptions, proceed with least-surprising option |
+| LOW / UNKNOWN | Source API/schema completely unknown | Discovery first ➔ Inspect repo/sources before blocking |
+
+---
+
+## Severity
+
+| Level | Definition | Action |
+|-------|-----------|--------|
+| CRITICAL | Pipeline failure, data loss, duplicate primary keys | Dừng pipeline ngay lập tức |
+| ERROR | Schema mismatch, null in required column | Chặn publish sang tầng tiếp theo |
+| WARNING | Freshness SLA breach, statistical value drift | Bắn alert nhưng cho phép publish |
+| INFO | Metadata metric logging, row count audit | Ghi log theo dõi |
+
+---
+
+## Evidence Format
+
+```
+[SEVERITY] path/to/pipeline_or_query.py:LINE
+Issue:      [specific data issue or failure mode]
+Confidence: HIGH
+Fix:        [specific change / assertion]
+```
+
+**Example:**
+```
+[CRITICAL] src/jobs/transform_silver.py:45
+Issue:      Deduplication performed AFTER PII masking, losing original identity key
+Confidence: HIGH
+Fix:        Reorder steps: Cast -> Deduplicate -> PII Masking -> Lineage
+```
+
+---
+
+## Retry Policy
+```
+Quality Gate or Pipeline execution fails
+  └─ Inspect failure layer & error logs
+       ├─ Data schema mismatch → Update contract or fix mapping → Retry 1 time
+       └─ Data corruption in source → EXIT: FAILED → Alert human engineer
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Critical architectural decision needed or breaking schema detected
+Missing:
+  - Source-to-target field mapping
+  - Migration plan for breaking schema change
+Questions:
+  1. Trường mới/đổi kiểu có migration plan chưa?
+  2. Quyết định kiến trúc này có ảnh hưởng tới hạ tầng production không?
+Recommended Assumptions (if proceeding with minor choice):
+  - Choose least-surprising project-consistent option
+  - Document rationale in summary report
+```
+
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["task"],
+  "optional_fields": ["source", "target", "contract_path", "load_strategy", "profile"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "user or qk-validation-gate",
+  "output_fields": ["pipeline_code", "contract_spec", "quality_gate_config", "exit_code"]
+}
+```

package/.agents/skills/qk-data-lifecycle/SKILL.md

@@ -168,6 +168,86 @@ Không lưu:
 
 
 
+### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
+- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
+  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
+  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
+
+---
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Convention / Architecture (vd: chiến lược migration backward-compatible, quy định FK).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Quyết định Architecture quan trọng (vd: chuẩn index CSDL, quy tắc phân trang mới).
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Thao tác thêm trường đơn giản hoặc temporary database fix.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+
+
+
 ### Pre-flight Retrieve (Trước khi thực thi)
 - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
   bắt buộc tra cứu: