@longph2102/v-flow 1.5.0

package/skills/implement/no-go-zone-guard/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: no-go-zone-guard
+description: "Ngăn Implement Agent đụng vào No-Go Zones trong context.md. Skill này LUÔN ACTIVE trong Phase B.1 — kiểm tra TRƯỚC MỖI file edit."
+trigger: "LUÔN ACTIVE trong B.1 — trước mỗi file edit"
+phase: "B.1"
+used_by:
+  - /v.implement
+  - /v.review
+hooks:
+  pre_file_edit: "Kiểm tra file path against No-Go Zones"
+---
+
+# No-Go Zone Guard — Bảo Vệ Vùng Code Cấm
+
+> ⚠️ Skill này **bắt buộc** trong B.1 — nhưng harness KHÔNG tự fire.
+> Implement Agent PHẢI **tự chạy** `.v-flow/skills/implement/no-go-zone-guard/scripts/check-nogo-zones.sh <file>` TRƯỚC mỗi file edit (đã ghi trong `implement-agent.md` Bước 2). Muốn enforce cứng → wire vào git pre-commit / CI (xem `constitution-enforcer/SKILL.md → Wiring enforcement thật`).
+>
+> → Xem `gotchas.md` cho lỗi phổ biến khi xử lý No-Go.
+> → Xem `examples/good/` cho workaround patterns.
+> → Xem `config.json` để customize enforcement level.
+> → `.v-flow/skills/implement/no-go-zone-guard/scripts/check-nogo-zones.sh <file>`: tự động phủ **Check 1/2** (path/dir), **Check 3** (import — advisory), **Check 5** (test→source). **Check 4** (config side-effect) vẫn cần agent rà thủ công.
+
+---
+
+## Khi nào KHÔNG áp dụng
+
+- Greenfield project (không có context.md → không có No-Go Zones)
+- File mới hoàn toàn (không nằm trong No-Go directory)
+
+---
+
+## Nguồn No-Go Zones
+
+Đọc từ các nguồn theo thứ tự ưu tiên:
+
+```
+1. .v-flow/context.md → §4 🚫 No-Go Zones     ← PRIMARY
+2. constitution.md → §7 No-Go Zones             ← SECONDARY  
+3. tasks.md → "No-Go Check" per-task             ← TASK-LEVEL
+```
+
+---
+
+## 3 Levels
+
+| Level | Marker | Nghĩa | Action |
+|-------|:------:|-------|--------|
+| 🔴 **Strict** | `🔴 Cao` | Tuyệt đối cấm — production, audited, PCI | **BLOCK** — không ngoại lệ |
+| 🟡 **Warning** | `🟡 Trung bình` | Nên tránh — nhiều service phụ thuộc | **WARN** — cần Tech Lead approval |
+| 🟢 **Caution** | `🟢 Thấp` | Cẩn thận — legacy code, side effects unknown | **LOG** — ghi lý do vào _session.md |
+
+---
+
+## Kiểm Tra — Cái Gì Cần Check
+
+> 💡 Đây là phần quan trọng nhất — **KHÔNG CHỈ KIỂM TRA FILE PATH**.
+
+### Check 1: Direct File Match
+```
+File đang edit nằm trong No-Go Zone?
+VD: routes/payment.js là No-Go → BLOCK
+```
+
+### Check 2: Parent Directory Match
+```
+File nằm trong directory là No-Go?
+VD: No-Go = "routes/payment/" → routes/payment/webhook.js cũng BLOCK
+```
+
+### Check 3: New Import From No-Go
+```
+File mới import/require từ No-Go module?
+VD: const auth = require('../middleware/auth') // auth.js là No-Go
+→ Import READ-ONLY ok, nhưng MODIFY behavior → cần xem xét
+```
+
+### Check 4: Config Side-Effects
+```
+Sửa shared config (env, DB config) có ảnh hưởng No-Go modules?
+VD: Thay đổi DB pool config → ảnh hưởng payment module
+```
+
+### Check 5: Test Files Tương Ứng
+```
+test/payment.test.js thuộc No-Go nếu routes/payment.js là No-Go?
+→ CÓ. Test file của No-Go module = No-Go.
+```
+
+---
+
+## Workaround Patterns
+
+> 💡 Khi cần interact với No-Go module mà KHÔNG sửa nó.
+
+### Pattern 1: Wrapper / Adapter
+Tạo file mới wrap interface No-Go module:
+```
+// adapters/payment-adapter.js (NEW file — OK)
+const payment = require('../no-go/payment'); // import OK
+module.exports = {
+  getStatus: (id) => payment.checkStatus(id), // wrap, không modify
+};
+```
+**Rule**: Adapter KHÔNG modify behavior — chỉ wrap hoặc extend.
+
+### Pattern 2: Event Bus
+Emit event thay vì gọi trực tiếp:
+```
+// Không gọi payment.process() trực tiếp
+eventBus.emit('payment:requested', data);
+// payment module listen event này (nếu nó đã support)
+```
+
+### Pattern 3: Interface Segregation
+Tạo interface, No-Go module implement nó. New code depend on interface, không direct dependency.
+
+### Pattern 4: API Gateway
+Gọi No-Go service qua HTTP API thay vì import trực tiếp (microservices pattern).
+
+---
+
+## Khi Phải Đụng No-Go Zone (Bất khả kháng)
+
+```
+1. DỪNG NGAY — không tự ý sửa
+2. Ghi vào _session.md:
+   "⚠️ TASK-{N} requires editing No-Go Zone: {file}. Reason: {why}"
+3. Set .flow-state.yaml: blocked = true, blocked_reason = "No-Go Zone conflict"
+4. Chờ Tech Lead quyết định:
+   - Option A: Approve exception (ghi approval vào _session.md)
+   - Option B: Redesign approach (update plan.md)
+   - Option C: Scope out (update spec.md)
+```
+
+---
+
+## No-Go Zone Types — Reference
+
+| Loại | Ví dụ | Rủi ro | Workaround |
+|------|-------|--------|-----------|
+| Payment/Billing | `routes/payment.js`, `services/stripe.js` | PCI compliance | Adapter pattern |
+| Auth/Identity | `middleware/auth.js`, `services/sso.js` | Cascading breakage | Interface segregation |
+| Core Infrastructure | `db/pool.js`, `config/env.js` | System-wide impact | Environment variables |
+| 3rd Party SDK | `lib/vendor-sdk.js` | Vendor-controlled | Wrapper pattern |
+| Legacy Critical | `legacy/core-engine.js` | Unknown side effects | Event bus |
+| Audited Code | `security/encryption.js` | Audit invalidation | Extend, don't modify |
+
+---
+
+## Wiring — Cưỡng chế cứng qua git (batch gate)
+
+`check-nogo-zones.sh` kiểm **một** file (agent gọi trước mỗi edit). `nogo-precommit.sh` chạy nó trên **toàn bộ git diff** → biến No-Go thành rào chắn thật, **không phụ thuộc agent nhớ**.
+
+**Pre-commit hook** (`.git/hooks/pre-commit`, `chmod +x`):
+```bash
+#!/bin/bash
+exec .v-flow/skills/implement/no-go-zone-guard/scripts/nogo-precommit.sh
+```
+→ chặn commit nếu chạm 🔴 Strict zone. Thêm `--strict-warn` để chặn cả 🟡.
+
+**CI (GitHub Actions)** — chặn PR:
+```yaml
+- name: No-Go Zone gate
+  run: bash .v-flow/skills/implement/no-go-zone-guard/scripts/nogo-precommit.sh --base origin/${{ github.base_ref }} --strict-warn
+```
+
+Exit: `0` sạch (hoặc chỉ 🟢 Low) · `1` chạm 🔴 (hoặc 🟡 khi `--strict-warn`). Mặc định: staged files. `--base <ref>`: so với base ref (CI/PR).
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho lỗi phổ biến — cập nhật liên tục.

package/skills/implement/no-go-zone-guard/config.json

@@ -0,0 +1,28 @@
+{
+  "_note": "setup_questions là PROMPT. Đáp án resolve persist vào .v-flow/config.yaml (nogo_strict_mode, nogo_source). Thiếu → dùng default dưới đây.",
+  "answers_persisted_to": ".v-flow/config.yaml",
+  "setup_questions": [
+    {
+      "id": "strict_mode",
+      "question": "No-Go Zone enforcement level?",
+      "options": ["strict", "warning", "log"],
+      "default": "strict",
+      "description": "strict = BLOCK mọi vi phạm. warning = WARN nhưng cho phép nếu có approval. log = chỉ ghi log."
+    },
+    {
+      "id": "nogo_source",
+      "question": "No-Go Zones đọc từ đâu?",
+      "options": ["context.md", "constitution.md", "both"],
+      "default": "both"
+    }
+  ],
+  "hooks": {
+    "pre_file_edit": "Kiểm tra file path against No-Go Zones list trước mỗi edit",
+    "pre_command": "Validate scope — command không ảnh hưởng No-Go Zone files"
+  },
+  "memory": {
+    "file": "nogo-violations.log",
+    "format": "[date] | [feature] | [task] | [file_attempted] | [nogo_zone] | [action_taken]",
+    "purpose": "Track violations — giúp identify patterns lặp lại"
+  }
+}

package/skills/implement/no-go-zone-guard/examples/good/adapter-workaround.md

@@ -0,0 +1,46 @@
+# Good Example — Adapter Pattern cho No-Go Zone
+
+## Context
+- No-Go Zone: `routes/payment.js` (PCI compliance — 🔴 Strict)
+- Task: T-006 cần lấy payment status để hiển thị trên product page
+- Problem: Cần gọi payment nhưng KHÔNG ĐƯỢC sửa payment module
+
+## Workaround: Adapter Pattern
+
+```javascript
+// ✅ MỚI: adapters/payment-adapter.js (file mới — OK)
+const paymentService = require('../routes/payment'); // import OK, không sửa
+
+/**
+ * Adapter cho payment module (No-Go Zone)
+ * KHÔNG modify behavior — chỉ wrap interface cần thiết
+ * Ref: T-006, No-Go: routes/payment.js
+ */
+module.exports = {
+  // Wrap method hiện có — pass through, không modify
+  getStatus: async (orderId) => {
+    return paymentService.checkPaymentStatus(orderId);
+  },
+  
+  // Format output cho product page — logic MỚI ở adapter, KHÔNG ở payment
+  getStatusForDisplay: async (orderId) => {
+    const status = await paymentService.checkPaymentStatus(orderId);
+    return {
+      isPaid: status.code === 'COMPLETED',
+      label: STATUS_LABELS[status.code] || 'Unknown',
+    };
+  },
+};
+
+const STATUS_LABELS = {
+  COMPLETED: 'Đã thanh toán',
+  PENDING: 'Đang xử lý',
+  FAILED: 'Thất bại',
+};
+```
+
+## Rules Applied
+- ✅ `routes/payment.js` KHÔNG bị sửa
+- ✅ Adapter chỉ WRAP — không modify return value của original
+- ✅ Logic mới (getStatusForDisplay) nằm ở adapter, không ở payment
+- ✅ Comment ghi rõ: No-Go reference + Task ID

package/skills/implement/no-go-zone-guard/gotchas.md

@@ -0,0 +1,27 @@
+# Gotchas — No-Go Zone Guard
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
+
+---
+
+## Anti-Patterns
+
+1. ❌ **"Chỉ refactor nhỏ thôi"** — Không có refactor nhỏ trong No-Go Zone.
+   - **Thực tế**: Rename variable trong payment.js → 3 services import nó break.
+
+2. ❌ **Quên test files** — `test/payment.test.js` cũng thuộc No-Go.
+   - **Lý do**: Sửa test → false confidence → miss regression.
+
+3. ❌ **Import chain** — File A import File B (No-Go) → sửa export interface B → A break.
+   - **Check**: `grep -r "require.*payment\|import.*payment" src/`
+
+4. ❌ **Config changes** — Sửa `.env` hoặc `config.js` có thể ảnh hưởng No-Go modules.
+   - **VD**: `DB_POOL_SIZE=5→10` → payment module connection behavior thay đổi.
+
+5. ❌ **Wrapper modify behavior** — Adapter pattern nhưng thay đổi return value.
+   - **Rule**: Adapter chỉ WRAP — pass through data unchanged.
+
+6. ✅ **Hỏi trước khi sửa** — Khi BẮT BUỘC đụng No-Go → DỪNG, ghi _session.md, chờ Tech Lead.
+
+7. ✅ **Document workaround** — Khi dùng adapter → ghi rõ TẠI SAO trong code comment.

package/skills/implement/no-go-zone-guard/scripts/check-nogo-zones.sh

@@ -0,0 +1,148 @@
+#!/bin/bash
+# check-nogo-zones.sh — Kiểm tra file có nằm trong No-Go Zone
+# Usage: ./check-nogo-zones.sh <file_path> [context.md_path]
+#
+# Exit codes:
+#   0 = File OK (không trong No-Go Zone; hoặc chỉ khớp mức 🟢 Thấp → LOG, được phép)
+#   1 = File BLOCKED (🔴 Strict — HOẶC zone không đánh mức → mặc định Strict, fail-safe)
+#   2 = File WARNING (🟡 cần Tech Lead approval)
+
+FILE="$1"
+CONTEXT="${2:-.v-flow/context.md}"
+
+if [ -z "$FILE" ]; then
+  echo "Usage: $0 <file_path> [context.md_path]"
+  exit 0
+fi
+
+if [ ! -f "$CONTEXT" ]; then
+  echo "✅ No context.md found — greenfield project, no No-Go Zones"
+  exit 0
+fi
+
+# Extract No-Go Zones section from context.md
+# Dùng `sed '$d'` (POSIX) thay cho `head -n -1` (GNU-only) — trên macOS/BSD `head -n -1`
+# lỗi → section rỗng → guard FAIL OPEN (báo PASS cho file cấm). Đây là bug an toàn.
+NOGO_SECTION=$(sed -n '/No-Go Zones/,/^##[^#]/p' "$CONTEXT" | sed '$d')
+
+if [ -z "$NOGO_SECTION" ]; then
+  echo "✅ No No-Go Zones defined in context.md"
+  exit 0
+fi
+
+# path_matches FILE ZONE → 0 nếu FILE LÀ zone, NẰM TRONG zone (dir), hoặc zone là 1
+# path-segment trọn vẹn của FILE. Dùng so khớp theo ranh giới path — KHÔNG substring
+# (tránh false positive: zone `auth.js` KHÔNG còn chặn nhầm `oauth.js`).
+path_matches() {
+  local file="$1" zone="$2"
+  zone="${zone#./}"; zone="${zone%/}"
+  case "$file" in
+    "$zone") return 0 ;;        # khớp path tuyệt đối
+    "$zone"/*) return 0 ;;      # file nằm trong thư mục zone
+    */"$zone") return 0 ;;      # zone là segment cuối (file/dir)
+    */"$zone"/*) return 0 ;;    # zone là segment giữa đường dẫn
+  esac
+  return 1
+}
+
+# Check 5: test file của 1 module No-Go cũng là No-Go.
+# Map ngược test file → source: test/payment.test.js → payment.js ; foo.spec.ts → foo.ts
+src_of_test() {
+  echo "$1" | sed -E 's#(^|/)(__tests__|__test__|tests?|spec)/##; s#\.(test|spec)\.([A-Za-z]+)$#.\2#'
+}
+
+# is_test_of FILE ZONE → 0 nếu FILE là test file có basename source == basename zone.
+# Heuristic theo basename (test path không mang thư mục source) — over-block an toàn cho zone.
+is_test_of() {
+  local file="$1" zone="$2" src
+  case "$zone" in */) return 1 ;; esac      # zone là thư mục, không phải file → bỏ
+  src=$(src_of_test "$file")
+  [ "$src" = "$file" ] && return 1          # không phải test file
+  [ "$(basename "$src")" = "$(basename "$zone")" ] && return 0
+  return 1
+}
+
+# Phân loại từng zone theo marker mức độ TRÊN DÒNG chứa nó. FAIL-SAFE: một path trong
+# backtick KHÔNG có marker (hoặc đánh 🔴/Cao/strict/critical) → STRICT (block). CHỈ hạ cấp
+# khi có marker rõ ràng: 🟡/Trung bình/warning → WARN; 🟢/Thấp → LOG. Tránh để vùng cấm
+# lọt qua chỉ vì tác giả quên đánh dấu mức độ (trước đây không marker = exit 0 im lặng).
+STRICT_ZONES=""; WARN_ZONES=""; LOG_ZONES=""
+while IFS= read -r line; do
+  zones=$(printf '%s\n' "$line" | grep -oE '`[^`]+`' | tr -d '`')
+  [ -z "$zones" ] && continue
+  if printf '%s' "$line" | grep -qi "🟢\|Thấp"; then
+    LOG_ZONES="$LOG_ZONES
+$zones"
+  elif printf '%s' "$line" | grep -qi "🟡\|Trung bình\|warning"; then
+    WARN_ZONES="$WARN_ZONES
+$zones"
+  else
+    STRICT_ZONES="$STRICT_ZONES
+$zones"
+  fi
+done <<EOF
+$NOGO_SECTION
+EOF
+
+# Check 1/2/5 — Strict (🔴) → BLOCK
+while IFS= read -r zone; do
+  [ -z "$zone" ] && continue
+  if path_matches "$FILE" "$zone"; then
+    echo "🚫 BLOCKED: '$FILE' matches Strict No-Go Zone: '$zone'"
+    echo "   Action: STOP — cannot edit this file"
+    exit 1
+  fi
+  if is_test_of "$FILE" "$zone"; then
+    echo "🚫 BLOCKED: '$FILE' là test của module No-Go '$zone' (Check 5)"
+    echo "   Action: STOP — test file của module No-Go cũng là No-Go"
+    exit 1
+  fi
+done <<EOF
+$STRICT_ZONES
+EOF
+
+# Check 1/2/5 — Warning (🟡) → cần Tech Lead approval
+while IFS= read -r zone; do
+  [ -z "$zone" ] && continue
+  if path_matches "$FILE" "$zone" || is_test_of "$FILE" "$zone"; then
+    echo "⚠️  WARNING: '$FILE' matches Warning No-Go Zone: '$zone'"
+    echo "   Action: Needs Tech Lead approval before editing"
+    exit 2
+  fi
+done <<EOF
+$WARN_ZONES
+EOF
+
+# 🟢 Thấp → LOG (được phép, chỉ ghi nhận — KHÔNG block, KHÔNG cần duyệt)
+while IFS= read -r zone; do
+  [ -z "$zone" ] && continue
+  if path_matches "$FILE" "$zone" || is_test_of "$FILE" "$zone"; then
+    echo "📝 LOG: '$FILE' thuộc No-Go Zone mức Thấp (🟢): '$zone' — được phép sửa, đã ghi nhận."
+    exit 0
+  fi
+done <<EOF
+$LOG_ZONES
+EOF
+
+# Check 3 (advisory) — file có import/require module No-Go không?
+if [ -f "$FILE" ] && [ -n "$STRICT_ZONES" ]; then
+  IMPORTED=""
+  while IFS= read -r zone; do
+    [ -z "$zone" ] && continue
+    base=$(basename "$zone"); base="${base%.*}"
+    [ -z "$base" ] && continue
+    if grep -Eq "(require|import|from)[^A-Za-z0-9_]+['\"][^'\"]*${base}" "$FILE" 2>/dev/null; then
+      IMPORTED="$IMPORTED $zone"
+    fi
+  done <<EOF
+$STRICT_ZONES
+EOF
+  if [ -n "$IMPORTED" ]; then
+    echo "ℹ️  NOTE: '$FILE' import module No-Go:$IMPORTED"
+    echo "   Import READ-ONLY OK — KHÔNG sửa behavior module No-Go, chỉ wrap/adapter."
+    echo "   (Check 4 — config side-effect — cần agent tự rà thủ công.)"
+  fi
+fi
+
+echo "✅ '$FILE' is NOT in any No-Go Zone"
+exit 0

package/skills/implement/no-go-zone-guard/scripts/nogo-precommit.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# nogo-precommit.sh — Batch No-Go gate over the git diff (pre-commit / CI).
+#
+# Wraps check-nogo-zones.sh across every changed file so a commit/PR that
+# touches a 🔴 Strict No-Go Zone is BLOCKED mechanically — not left to the
+# agent reading context.md and "remembering". This is the file-path enforcement
+# leg that turns No-Go from documentation into a guard rail.
+#
+# Usage:
+#   nogo-precommit.sh                      # staged files (default — pre-commit)
+#   nogo-precommit.sh --base origin/main   # files changed vs a base ref (CI/PR)
+#   nogo-precommit.sh --strict-warn        # treat 🟡 Warning zones as blocking too
+#   nogo-precommit.sh --context path/to/context.md
+#
+# Exit 0 = clean (or only 🟢 Low / advisory).
+# Exit 1 = a 🔴 Strict zone was touched (or 🟡 Warning under --strict-warn),
+#          or the guard is misconfigured (fail-safe: block rather than allow).
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK="$SCRIPT_DIR/check-nogo-zones.sh"
+
+BASE=""
+STRICT_WARN=0
+CONTEXT=".v-flow/context.md"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --base) BASE="$2"; shift 2 ;;
+    --strict-warn) STRICT_WARN=1; shift ;;
+    --context) CONTEXT="$2"; shift 2 ;;
+    -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+    *) echo "Unknown arg: $1"; exit 1 ;;
+  esac
+done
+
+if [ ! -f "$CHECK" ]; then
+  echo "🚫 No-Go guard misconfigured: not found: $CHECK"
+  exit 1   # fail-safe — block rather than silently allow
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "✅ Not a git repo — No-Go batch gate skipped"
+  exit 0
+fi
+
+# Determine the changed-file list.
+if [ -n "$BASE" ]; then
+  FILES=$(git diff --name-only "$BASE"...HEAD 2>/dev/null || git diff --name-only "$BASE" HEAD)
+else
+  FILES=$(git diff --cached --name-only)
+  [ -z "$FILES" ] && FILES=$(git diff --name-only HEAD)   # manual run convenience
+fi
+
+if [ -z "$FILES" ]; then
+  echo "✅ No changed files — No-Go gate clean"
+  exit 0
+fi
+
+BLOCKED=""
+WARNED=""
+
+while IFS= read -r file; do
+  [ -z "$file" ] && continue
+  out=$(bash "$CHECK" "$file" "$CONTEXT")
+  code=$?
+  case "$code" in
+    1) BLOCKED="$BLOCKED\n  $file" ; echo "$out" ;;
+    2) WARNED="$WARNED\n  $file" ; echo "$out" ;;
+  esac
+done <<EOF
+$FILES
+EOF
+
+echo ""
+echo "── No-Go Batch Gate ──"
+
+if [ -n "$BLOCKED" ]; then
+  echo -e "🚫 BLOCKED — changed files in 🔴 Strict No-Go Zone:$BLOCKED"
+  echo "   Commit/PR rejected. Move the change out of the zone, or get Tech Lead sign-off + update context.md."
+  exit 1
+fi
+
+if [ -n "$WARNED" ]; then
+  echo -e "⚠️  WARNING — changed files in 🟡 No-Go Zone (cần Tech Lead duyệt):$WARNED"
+  if [ "$STRICT_WARN" -eq 1 ]; then
+    echo "   --strict-warn: treated as blocking."
+    exit 1
+  fi
+  echo "   Advisory (không chặn). Dùng --strict-warn để chặn ở CI."
+  exit 0
+fi
+
+echo "✅ No changed file touches a Strict/Warning No-Go Zone"
+exit 0

package/skills/implement/tdd-driver/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: tdd-driver
+description: "Hướng dẫn Implement Agent tuân thủ TDD (Red-Green-Refactor) khi implement tasks. Agent PHẢI đọc skill này trước khi bắt đầu bất kỳ TASK nào."
+trigger: "Khi bắt đầu implement task từ tasks.md"
+phase: "B.1"
+used_by:
+  - /v.implement
+hooks:
+  pre_implement: "Map TC-xxx từ test-cases.md cho TASK hiện tại"
+  post_implement: "Chạy full test suite, verify không regression"
+---
+
+# TDD Driver — Implement Đúng Quy Trình
+
+> ⚠️ Đây là **Skill bắt buộc** cho Implement Agent.
+> Đọc trước khi implement. TDD không phải suggestion — đây là RULE.
+>
+> → Xem `gotchas.md` cho lỗi phổ biến khi làm TDD.
+> → Xem `examples/good/` cho mẫu TDD cycle đúng chuẩn.
+> → Xem `config.json` để customize test framework, coverage target.
+> → Xem `scripts/` cho automation (nếu có).
+
+---
+
+## Iron Law — Không code production khi chưa có test FAIL trước
+
+```
+KHÔNG VIẾT CODE PRODUCTION KHI CHƯA CÓ MỘT TEST ĐANG FAIL.
+```
+
+Lỡ viết code TRƯỚC test → **xóa code đó, làm lại từ test**. Không giữ "để tham khảo", không "chỉnh lại trong lúc viết test" (đó vẫn là test-after). Lý do cốt lõi: **nếu không tận mắt thấy test FAIL, bạn không biết nó có thực sự kiểm đúng thứ cần kiểm** — test viết sau code thường pass ngay và chứng minh số 0.
+
+> ⚠️ Đây là chỗ agent hay **tự ngụy biện để bỏ qua**. Gặp ý nghĩ "thôi lần này bỏ TDD" = tín hiệu DỪNG, quay lại viết test trước. Bảng dưới đập lại từng cái:
+
+| Ngụy biện | Sự thật |
+|-----------|---------|
+| "Đơn giản quá, khỏi test" | Code đơn giản vẫn hỏng. Test mất 30 giây. |
+| "Test sau cũng vậy thôi" | Test-after = "code này làm gì?"; test-first = "code này NÊN làm gì?". Test-after thiên lệch theo cái đã viết. |
+| "Tôi test tay rồi" | Tay = ad-hoc, không tái chạy được, không có dấu vết. |
+| "Xóa mấy giờ code phí lắm" | Sunk cost. Giữ code chưa được test = nợ kỹ thuật. |
+| "Giữ lại tham khảo, viết test trước" | Bạn sẽ "phỏng theo" nó → vẫn là test-after. Xóa là xóa. |
+| "Test khó viết quá" | Khó test = thiết kế đang coupling/khó dùng. Nghe theo test → tách interface/DI. |
+| "TDD cứng nhắc, tôi đang thực dụng" | TDD MỚI là thực dụng: bắt bug trước commit, chặn regression, refactor tự do. |
+
+---
+
+## Khi nào KHÔNG áp dụng strict TDD
+
+- Tạo file config/constant (không có logic → không cần test trước)
+- Chạy migration/DDL (test ở integration level, không unit)
+- Viết documentation, comments
+
+---
+
+## Đặc Thù Và Quy Ước
+
+> 💡 Phần này chứa thông tin Agent thường bỏ sót hoặc làm sai.
+
+### 1. Nguồn test cases — quan hệ TC-xxx ↔ TDD block
+
+> 🔑 Hai tầng **bổ sung nhau**, KHÔNG mâu thuẫn. Đừng đọc "không tự nghĩ test" thành "không được gõ test".
+
+| Tầng | Ở đâu | Ai tạo | Vai trò |
+|------|-------|--------|---------|
+| `TC-xxx` | `test-cases.md` (B.0b) | Test Agent | Catalog **ý đồ test chính thức** (scenario), trace tới AC/REQ |
+| TDD block | trong task ở `tasks.md` | Plan Agent (provisional) | Checklist Red→Green để Implement Agent **viết code test** hiện thực TC |
+
+**Quy tắc:**
+- "**KHÔNG tự nghĩ test mới**" = KHÔNG bịa scenario/ý đồ nằm ngoài spec/AC. **CÓ viết code test** — đó chính là việc của TDD.
+- Task **có `TC-xxx`** → hiện thực đúng các TC đó (theo TDD block).
+- Task **chưa có `TC-xxx` nhưng có TDD block** (provisional — Test Agent chạy song song B.0b) → **VẪN implement**: viết test theo TDD block (bám `Done khi`/AC), và ghi `_session.md`: `T-{N}: cần TC backfill ở R.0` để Test Agent đối soát sau. **KHÔNG hard-stop.**
+- Chỉ **DỪNG (blocked)** khi task **không có CẢ `TC-xxx` LẪN TDD block VÀ không có AC** để bám → ghi `_session.md`: `T-{N} blocked — không có test spec lẫn AC`.
+
+### 2. Concern resolution trong TDD cycle
+- Đọc `_session.md` → tìm W-xxx concerns assigned cho task hiện tại
+- Viết test cho concern scenario TRƯỚC khi implement fix
+- Ghi kết quả: `W-xxx: Resolved — [mô tả fix]` vào `_session.md`
+
+### 3. Test naming convention
+- **Pattern**: `should_<expected_behavior>_when_<condition>`
+- VD: `should_return_404_when_product_not_found`
+- KHÔNG: `test1`, `testLogin`, `it_works`
+
+### 4. Mocking strategy
+- Mock **external dependencies** (DB, API, file system) trong unit tests
+- KHÔNG mock module đang test (test real behavior)
+- Document mock behavior trong test file header comment
+- Đọc `config.json → test_framework` để biết mock library phù hợp
+- **Test anti-patterns — TRÁNH** (test phải kiểm hành vi THẬT, không kiểm hành vi của mock):
+  - ❌ **Assert lên mock** (vd `getByTestId('sidebar-mock')`) → chỉ chứng minh mock tồn tại. Sửa: test component thật / assert lên `role`/hành vi thật.
+  - ❌ **Method test-only trong class production** (vd `destroy()` chỉ test gọi) → đẩy sang `test-utils/`, đừng làm bẩn production (YAGNI).
+  - ❌ **Mock khi chưa hiểu dependency** → mock nuốt mất side-effect mà test phụ thuộc. Chạy test với impl thật TRƯỚC, hiểu nó cần gì, rồi mock ở **tầng thấp nhất** (cái chậm/external), không mock hàm cấp cao test đang dựa vào.
+  - ❌ **Mock thiếu field** → mirror ĐẦY ĐỦ cấu trúc API thật, không chỉ field test này dùng (downstream đọc field thiếu → fail âm thầm).
+
+### 5. V-Flow Integration Points
+- **test-cases.md** (B.0b) → nguồn TC. KHÔNG tự nghĩ TC mới
+- **plan.md** (B.0a) → architecture cần follow khi implement
+- **constitution.md** → naming convention, patterns
+- **_session.md** → ghi trace mỗi TDD cycle completion
+- **No-Go Zone Guard** → cross-check TRƯỚC khi tạo file mới
+
+### 6. Coverage Tracking
+- Đọc target từ `.v-flow/config.yaml → coverage_target` (đáp án setup đã resolve); thiếu file → fallback default `config.json` = 80%
+- Sau mỗi task: verify coverage ≥ target (gate này nằm ở `implement-agent.md` Bước 4)
+- Nếu dưới target → viết thêm tests cho untested branches
+- Ghi vào `tdd-history.log`: task, tests written, coverage delta
+
+> ⚠️ `hooks: pre_implement/post_implement` ở frontmatter chỉ là **ý định** — harness KHÔNG tự fire. Implement Agent tự thực hiện trong quy trình B.1.
+
+---
+
+## Red-Green-Refactor — Signals Nhận Biết
+
+| Phase | Signal đúng | Signal sai |
+|-------|------------|-----------|
+| 🔴 **RED** | Test FAIL với expected reason | Test FAIL vì syntax error |
+| 🔴 **RED** | Test FAIL vì function chưa tồn tại | Test PASS ngay → test sai |
+| 🟢 **GREEN** | Test PASS sau khi viết code tối thiểu | Test PASS nhưng code quá complex |
+| 🟢 **GREEN** | ALL tests pass (cũ + mới) | Chỉ test mới pass, test cũ break |
+| 🔵 **REFACTOR** | Code cleaner, tests vẫn pass | Tests break → undo refactor |
+| 🔵 **REFACTOR** | Naming/structure theo constitution | Thêm feature mới (không phải refactor) |
+
+---
+
+## Per-Task Verification Signals
+
+Agent tự verify trước khi chuyển task. Nếu BẤT KỲ signal nào ❌ → không chuyển task:
+
+| Signal | Verify bằng cách | Nếu fail |
+|--------|------------------|----------|
+| Spec-fit (đúng & đủ) | Diff task khớp ĐÚNG `AC-NN`/`TC-xx` của task — **không thiếu** (đủ AC) **và không thừa** (không thêm field/flag/endpoint/abstraction không ai yêu cầu) | Thiếu → bổ sung; Thừa → gỡ bỏ (over-build vi phạm YAGNI) |
+| TC mapped | Grep TC-xxx trong test-cases.md cho TASK hiện tại | Có TDD block/AC → vẫn code, log "TC backfill R.0". Không có gì để bám → DỪNG, báo Test Agent |
+| Test wrote first | Git diff: test file created TRƯỚC impl file | Nếu ngược → commit history sai |
+| Red confirmed | Test output showed FAIL trước khi viết impl | Nếu pass ngay → test sai, fix test |
+| Green confirmed | ALL tests pass (cũ + mới) | Nếu test cũ break → regression |
+| Refactored | Code follows constitution naming/patterns | Nếu skip → tech debt |
+| No-Go safe | File list không overlap No-Go Zones | Nếu overlap → BLOCK |
+| Concerns | W-xxx resolved nếu có | Nếu skip → R.1 sẽ reject |
+| Trace logged | _session.md có entry cho task | Nếu thiếu → audit trail mất |
+
+---
+
+## Edge Cases
+
+### Test quá khó viết
+→ **Signal**: Design problem. Tightly coupled code = hard to test.
+→ **Action**: Ghi vào `_session.md`, suggest refactor approach. Viết simplest possible test.
+
+### External dependency không mock được
+→ **Action**: Tạo interface/adapter, mock interface. Test real implementation ở integration level.
+
+### Task quá lớn cho 1 TDD cycle
+→ **Action**: Split sub-tasks. Mỗi sub-task = 1 TDD cycle. Update `tasks.md`.
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` để tránh lỗi phổ biến — cập nhật liên tục.