@longph2102/v-flow 1.5.0

package/skills/prototype/examples/good/prototype-notes-ui.md

@@ -0,0 +1,109 @@
+# Mẫu Prototype Notes — ✅ Tốt (UI Branch)
+
+> Đây là mẫu `prototype-notes.md` đúng format cho **UI branch**.
+> Xem `good/prototype-notes.md` cho mẫu LOGIC branch.
+
+---
+
+```markdown
+# Prototype Notes — Feature 012: Dashboard Analytics Panel
+
+**Date**: 2026-05-20
+**Agent**: Prototype Agent
+**Branch**: UI
+**Phase**: S.1.5
+
+## Câu hỏi được trả lời
+
+> "Dashboard analytics panel nên hiển thị theo layout nào?
+> REQ-U03 nêu 'user có thể xem tổng quan metrics' nhưng không chỉ định
+> layout — sidebar metrics vs card grid vs table view đều khả thi."
+
+**REQ refs**: REQ-U03, REQ-O01
+
+## Sub-shape
+
+**Sub-shape A** — Embedded vào existing route `/dashboard`
+
+Lý do: Feature analytics panel sẽ nằm trong `/dashboard` đã có. Đặt variants
+vào existing page để kiểm tra xem layout nào hoạt động tốt với header/sidebar
+thật, không phải trong vacuum.
+
+## Design source
+
+`/DESIGN.md` — project override (tồn tại ở project root)
+
+## Run command
+
+```bash
+# Dev server phải đang chạy (Angular)
+ng serve
+
+# Mở trình duyệt tại:
+# http://localhost:4200/dashboard?variant=A   ← Card Grid
+# http://localhost:4200/dashboard?variant=B   ← Sidebar Metrics
+# http://localhost:4200/dashboard?variant=C   ← Table View
+```
+
+## Variants
+
+| Variant | Mô tả | Primary affordance |
+|---|---|---|
+| A | Card Grid — 4 metric cards across top, chart below | Glance metrics |
+| B | Sidebar Metrics — left sidebar với numbers, main area là chart | Deep analysis |
+| C | Table View — tất cả metrics trong sortable table, no chart | Export-friendly |
+
+## Kết quả thực hiện
+
+User đã flip qua 3 variants với real data (~20 phút):
+
+- [x] **Variant A** — "Card grid trông đẹp nhưng mất quá nhiều vertical space. Chart bị đẩy xuống dưới fold."
+- [x] **Variant B** — "Sidebar layout tốt hơn — chart luôn visible. Nhưng sidebar quá rộng trên mobile."
+- [x] **Variant C** — "Table useful cho export nhưng không phải default view người dùng cần."
+- [x] **Feedback quan trọng**: "Tôi muốn header của B (sidebar) nhưng sidebar collapse được trên mobile"
+
+## Verdict
+
+**VALIDATED** ✅
+
+Variant B (Sidebar Metrics) được chọn làm hướng chính, với yêu cầu bổ sung:
+sidebar phải responsive/collapsible trên mobile.
+
+## Spec impact
+
+- **REQ-U03**: Cần cập nhật AC: "Analytics panel dùng sidebar layout. Sidebar collapse trên màn hình < 768px."
+- **REQ-O01**: Không thay đổi — Table View (Variant C) sẽ là secondary view/export mode
+
+## Decisions to carry-forward → _session.md
+
+1. **Layout pattern**: Sidebar left (240px desktop) + main chart area — không phải card grid
+2. **Responsive**: Sidebar collapse về hamburger menu trên mobile (`< 768px`)
+3. **Variant C insight**: Table view được giữ lại làm "Export mode" — Plan Agent cần thêm toggle
+4. **Design token**: Dùng `--surface-secondary` từ DESIGN.md cho sidebar background
+
+## Routing
+
+→ Sửa REQ-U03 trong `spec.md` (thêm sidebar AC + mobile collapse AC)
+→ Sau khi sửa spec → `/v.plan + /v.test` (song song)
+
+## Cleanup
+
+- [ ] Xóa `.v-flow/features/012/prototype/` sau khi Plan Agent đọc notes này
+- [ ] Xóa `VariantA`, `VariantB`, `VariantC` components khỏi `/dashboard`
+- [ ] Xóa `PrototypeSwitcher` khỏi `/dashboard` route
+- [x] `prototype-notes.md` đã được ghi đầy đủ
+- [x] `_session.md` đã được append
+- [x] `.flow-state.yaml` đã được update: `artifacts.prototype.verdict = VALIDATED`
+```
+
+---
+
+## Tại sao mẫu này tốt
+
+| Điểm | Lý do |
+|---|---|
+| Ghi rõ **Sub-shape A** và lý do | Tránh G-005 — không tạo route mới khi có existing page |
+| Liệt kê **3 variants với mô tả rõ** | Plan Agent hiểu design space đã được explore |
+| **Feedback verbatim** ("Tôi muốn header của B...") | Ghi lại insight thật, không chỉ "B tốt hơn" |
+| **Spec impact cụ thể** | BA Agent biết chính xác AC nào cần thêm |
+| **Cleanup checklist đầy đủ** | Không để variant components rot trong codebase |

package/skills/prototype/examples/good/prototype-notes.md

@@ -0,0 +1,67 @@
+# Mẫu Prototype Notes — ✅ Tốt
+
+> Đây là mẫu `prototype-notes.md` đúng format và đủ thông tin.
+> Xem `bad/prototype-notes.md` để biết mẫu thiếu thông tin.
+
+---
+
+```markdown
+# Prototype Notes — Feature 005: Order Cancellation Flow
+
+**Date**: 2026-05-15
+**Agent**: Prototype Agent
+**Branch**: LOGIC
+**Phase**: S.1.5
+
+## Câu hỏi được trả lời
+
+> "State machine của Order cancellation xử lý case concurrent cancel (2 users cancel cùng 1 order) như thế nào? REQ-S02 không chỉ định behavior khi CANCELLING → CANCELLED bị race condition."
+
+**REQ refs**: REQ-S02, REQ-E05
+
+## Run command
+
+```bash
+pnpm prototype:005
+# hoặc: tsx .v-flow/features/005/prototype/tui.ts
+```
+
+## Kết quả thực hiện
+
+User đã interact với prototype ~15 phút, test các case:
+- [x] Single user cancel → `PENDING → CANCELLING → CANCELLED` ✅
+- [x] Cancel sau khi đã ship → correctly rejected bởi state machine ✅  
+- [x] **Concurrent cancel (2 requests)**: First request wins, second nhận `AlreadyCancellingError` ⚠️
+- [x] Cancel order đã CANCELLED → `AlreadyCancelledError` ✅
+
+**Phát hiện quan trọng**: `AlreadyCancellingError` case chưa được định nghĩa trong REQ-S02. Hiện prototype trả về generic error. User confirm: "Đây là behavior đúng — cần thêm vào spec."
+
+## Verdict
+
+**VALIDATED** ✅
+
+State machine logic cơ bản đúng. Phát hiện 1 gap trong spec cần bổ sung.
+
+## Spec impact
+
+- **REQ-S02**: Cần thêm AC: "Khi order đang ở trạng thái CANCELLING, request cancel thứ hai phải nhận `AlreadyCancellingError` (HTTP 409)"
+- **Không cần REQ mới** — là AC bổ sung cho REQ-S02 hiện có
+
+## Decisions to carry-forward → _session.md
+
+1. State machine pattern: Pure reducer `(OrderState, CancelAction) => OrderState` — liftable vào `OrderCancellationUseCase`
+2. Error types cần định nghĩa: `AlreadyCancellingError`, `AlreadyCancelledError`, `ShippedOrderError`
+3. Concurrent access: First-write-wins với optimistic lock — Plan Agent cần design DB transaction cho case này
+
+## Routing
+
+→ Sửa REQ-S02 trong `spec.md` (thêm AC)  
+→ Sau khi sửa spec → `/v.plan + /v.test` (song song)
+
+## Cleanup
+
+- [ ] Xóa `.v-flow/features/005/prototype/` sau khi Plan Agent đọc notes này
+- [x] `prototype-notes.md` đã được ghi đầy đủ
+- [x] `_session.md` đã được append
+- [x] `.flow-state.yaml` đã được update: `artifacts.prototype.verdict = VALIDATED`
+```

package/skills/prototype/gotchas.md

@@ -0,0 +1,128 @@
+# Prototype Skill — Gotchas
+
+> Cập nhật liên tục khi Agent mắc lỗi mới. Mỗi gotcha = 1 lesson learned từ thực tế.
+
+---
+
+## G-001: Prototype trước khi có câu hỏi rõ ràng
+
+**Lỗi**: Agent bắt đầu build prototype ngay mà chưa viết rõ câu hỏi cần trả lời.
+
+**Hậu quả**: Prototype scope creep — người dùng không biết prototype này đang kiểm tra gì, không thể ra verdict.
+
+**Fix**: Bắt buộc ghi `# Question: ...` ở đầu README prototype TRƯỚC khi viết 1 dòng code. Nếu câu hỏi chưa rõ → hỏi user hoặc detect từ spec trước.
+
+---
+
+## G-002: Chọn sai branch
+
+**Lỗi**: Câu hỏi về state machine nhưng tạo UI prototype. Hoặc câu hỏi về layout nhưng tạo LOGIC TUI.
+
+**Hậu quả**: Prototype trả lời sai câu hỏi, waste toàn bộ thời gian.
+
+**Fix**: Đọc lại SKILL.md branch selection guide. Rule of thumb: nếu câu hỏi kết thúc bằng "có đúng không?" → LOGIC; "nên trông như thế nào?" → UI.
+
+---
+
+## G-003: LOGIC branch — Trộn TUI code vào logic module
+
+**Lỗi**: `logic.ts` có `console.log`, readline, hoặc escape codes (`\x1b[1m`).
+
+**Hậu quả**: Logic module không portable — không thể lift vào real code sau khi prototype done.
+
+**Fix**: Logic module phải 100% pure. TUI là thin shell bọc ngoài. `console.log` chỉ được xuất hiện trong `tui.ts`, không bao giờ trong `logic.ts`.
+
+---
+
+## G-004: UI branch — Variants chỉ khác màu
+
+**Lỗi**: Tạo 3 variants nhưng chúng chỉ khác color scheme hoặc spacing nhỏ.
+
+**Hậu quả**: Không phải UI prototype thật — chỉ là tweak. Không giúp user ra quyết định về structure.
+
+**Fix**: Mỗi variant phải có **khác biệt về structure**: layout khác (sidebar vs top nav vs cards), information hierarchy khác, primary affordance khác. Nếu 2 variants quá giống → redo 1 cái với explicit constraint "no card grid" hoặc "no sidebar".
+
+---
+
+## G-005: UI branch — Bỏ qua Sub-shape A
+
+**Lỗi**: Luôn tạo new throwaway route (Sub-shape B) mà không xét Sub-shape A (embed trong existing page).
+
+**Hậu quả**: Prototype chạy trong vacuum — mọi variant đều trông ổn vì không có real data, real header, real sidebar. Design issues chỉ lộ ra khi đặt trong context thật.
+
+**Fix**: Luôn hỏi "có existing page nào có thể host variants này không?" trước khi chọn Sub-shape B. Nếu có → Sub-shape A là default.
+
+---
+
+## G-006: Scope creep — Prototype trở thành MVP
+
+**Lỗi**: Prototype được thêm error handling, tests, abstractions, auth integration.
+
+**Hậu quả**: Tốn thời gian gấp 10x; khó xóa khi done; đôi khi bị promote lên production dưới prototype constraints.
+
+**Fix**: Mỗi khi muốn thêm gì → hỏi "Cái này có giúp trả lời câu hỏi không?" Nếu không → đừng thêm. Prototype là throwaway, không phải MVP.
+
+---
+
+## G-007: Không update `.flow-state.yaml` sau verdict
+
+**Lỗi**: Có verdict rồi nhưng quên update `artifacts.prototype.*` trong `.flow-state.yaml`.
+
+**Hậu quả**: `/v.status` dashboard hiển thị sai pipeline state. Plan Agent không biết prototype đã done.
+
+**Fix**: Sau khi ghi `prototype-notes.md` → ngay lập tức update `.flow-state.yaml`. Thứ tự bắt buộc: notes → session → flow-state → cleanup code.
+
+**Validate**: Chạy `.v-flow/skills/prototype/scripts/check-flow-state.sh <feature-number>` để verify.
+
+---
+
+## G-008: `--req` flag nhưng REQ không có ambiguity
+
+**Lỗi**: User dùng `--req REQ-E01` nhưng REQ-E01 rõ ràng, không ambiguous.
+
+**Hậu quả**: Prototype giải quyết thứ không cần giải quyết — waste effort.
+
+**Fix**: Dù user chỉ định `--req`, vẫn phải đọc REQ đó và confirm với user "REQ này cụ thể rồi, bạn có chắc muốn prototype không?" Nếu user confirm → tiến hành, ghi rõ lý do trong prototype-notes.md.
+
+---
+
+## G-009: Prototype không chạy được ngay (one-command requirement)
+
+**Lỗi**: User cần thực hiện 4-5 bước setup trước khi chạy prototype.
+
+**Hậu quả**: Friction ngăn user interact sớm với prototype. Prototype mất đi giá trị "fast feedback".
+
+**Fix**: Test run command trước khi hand over. Với HTML mode: mở file trong browser phải work ngay (inline JS, không external deps). Với LOGIC: `pnpm prototype:NNN` phải chạy được ngay từ project root.
+
+---
+
+## G-010: Không cleanup sau verdict
+
+**Lỗi**: `prototype/` folder vẫn còn trong `.v-flow/features/NNN/` sau khi có verdict.
+
+**Hậu quả**: Code prototype (không có tests, không production-quality) bị confuse với real code. Repo bloat.
+
+**Fix**: Luôn nhắc user xóa `prototype/` sau khi verdict đã được ghi vào `prototype-notes.md`. Chỉ giữ `prototype-notes.md`.
+
+**Validate**: Chạy `.v-flow/skills/prototype/scripts/check-prototype-cleanup.sh` (không cần args) để scan tất cả features.
+
+---
+
+## G-011: Xung đột phím nhập liệu trong TUI (Raw Mode Input Crash)
+
+**Lỗi**: Agent viết code TUI để hỏi người dùng nhập liệu (nhập số tiền, tên, câu trả lời) nhưng vẫn giữ nguyên chế độ lắng nghe phím Raw Mode (`setRawMode(true)`).
+
+**Hậu quả**: Khi người dùng nhấn phím đầu tiên để nhập liệu, TUI hiểu nhầm đó là một phím tắt menu, gây ra lỗi crash chương trình ngay lập tức hoặc nhảy menu sai lệch.
+
+**Fix**: Bắt buộc phải tắt Raw Mode (`process.stdin.setRawMode(false)`) và pause stdin trước khi tạo giao diện `readline`/`prompt`. Sau khi nhận được dữ liệu (User nhấn Enter), mới bật lại Raw Mode (`setRawMode(true)`) và resume stdin để nhận phím tắt. Xem blueprint mẫu trong `LOGIC.md` phần `4.5. Handling Text & Number Inputs`.
+
+---
+
+## G-012: Bàn giao "mù" (Blind Handover)
+
+**Lỗi**: Agent tạo xong mã nguồn prototype và đưa ngay lệnh chạy cho người dùng mà không tự chạy thử trước.
+
+**Hậu quả**: Người dùng nhận được lệnh nhưng không chạy được do lỗi cú pháp TypeScript, lỗi đường dẫn import path (`@/` resolving), hoặc thiếu thư viện phụ thuộc chưa cài đặt.
+
+**Fix**: Agent bắt buộc phải chạy thử lệnh (sử dụng `run_command` trên terminal của workspace) và đảm bảo chương trình biên dịch/khởi động thành công không bị crash trong ít nhất 500ms - 1s trước khi bàn giao lệnh chạy cho người dùng.
+

package/skills/prototype/scripts/check-flow-state.ps1

@@ -0,0 +1,112 @@
+# check-flow-state.ps1 — Kiểm tra .flow-state.yaml đã được update sau prototype
+# Usage: .\check-flow-state.ps1 [<feature-number>]
+#        .\check-flow-state.ps1 005
+#
+# Checks: artifacts.prototype.* fields tồn tại và có giá trị
+
+param(
+    [string]$FeatureNum = ""
+)
+
+# ── Resolve feature dir & flow-state path ─────────────────────────
+
+if (-not $FeatureNum) {
+    # Auto-detect: tìm feature có prototype-notes.md
+    $featureDir = Get-Item ".v-flow/features/*/" -ErrorAction SilentlyContinue |
+        Where-Object { Test-Path (Join-Path $_.FullName "prototype-notes.md") } |
+        Select-Object -First 1
+
+    if (-not $featureDir) {
+        Write-Host "❌ Cannot find feature directory with prototype-notes.md" -ForegroundColor Red
+        Write-Host "   Usage: .\check-flow-state.ps1 <feature-number>  (e.g. .\check-flow-state.ps1 005)"
+        exit 1
+    }
+    $flowState = Join-Path $featureDir.FullName ".flow-state.yaml"
+} else {
+    $padded = $FeatureNum.PadLeft(3, '0')
+    $featureDir = Get-Item ".v-flow/features/$padded-*/" -ErrorAction SilentlyContinue | Select-Object -First 1
+    if (-not $featureDir) {
+        $featureDir = [PSCustomObject]@{ FullName = ".v-flow/features/$FeatureNum/" }
+    }
+    $flowState = Join-Path $featureDir.FullName ".flow-state.yaml"
+}
+
+if (-not (Test-Path $flowState)) {
+    Write-Host "❌ .flow-state.yaml not found: $flowState" -ForegroundColor Red
+    exit 1
+}
+
+$content = Get-Content $flowState -Raw
+Write-Host "📋 Flow State Check (prototype section): $flowState"
+Write-Host "════════════════════════════════════════════════════"
+$errors   = 0
+$warnings = 0
+
+# 1. Section artifacts.prototype tồn tại
+Write-Host ""
+Write-Host "### 1. Prototype Section Exists"
+if ($content -match "prototype") {
+    Write-Host "   ✅ 'prototype' section found" -ForegroundColor Green
+} else {
+    Write-Host "   ❌ No 'prototype' section in .flow-state.yaml" -ForegroundColor Red
+    Write-Host "      Add: artifacts.prototype.verdict, artifacts.prototype.branch, etc."
+    $errors++
+}
+
+# 2. Verdict đã được điền
+Write-Host ""
+Write-Host "### 2. Verdict Field"
+if ($content -match "(?i)verdict\s*:\s*(VALIDATED|REJECTED|INCONCLUSIVE)") {
+    $verdict = $Matches[1].ToUpper()
+    Write-Host "   ✅ verdict: $verdict" -ForegroundColor Green
+} elseif ($content -match "(?i)verdict\s*:\s*(null|~|`"`")") {
+    Write-Host "   ❌ verdict is empty/null — prototype not yet concluded" -ForegroundColor Red
+    $errors++
+} else {
+    Write-Host "   ⚠️  verdict field not found under prototype section" -ForegroundColor Yellow
+    $warnings++
+}
+
+# 3. Branch đã được điền
+Write-Host ""
+Write-Host "### 3. Branch Field"
+if ($content -match "(?i)branch\s*:\s*(LOGIC|UI)") {
+    $branch = $Matches[1].ToUpper()
+    Write-Host "   ✅ branch: $branch" -ForegroundColor Green
+} elseif ($content -match "(?i)branch\s*:\s*(null|~|`"`")") {
+    Write-Host "   ⚠️  branch field empty/missing (should be LOGIC or UI)" -ForegroundColor Yellow
+    $warnings++
+} else {
+    Write-Host "   ⚠️  branch field not found (should be LOGIC or UI)" -ForegroundColor Yellow
+    $warnings++
+}
+
+# 4. Phase hiện tại có tiến sang B.0 chưa
+Write-Host ""
+Write-Host "### 4. Pipeline Phase"
+if ($content -match "(?i)(current_phase|phase)\s*:\s*[`"']?([SBR]\.\d+[\d.]*)[`"']?") {
+    $currentPhase = $Matches[2]
+    Write-Host "   ℹ️  Current phase: $currentPhase"
+    if ($currentPhase -eq "S.1.5") {
+        Write-Host "   ⚠️  Still at S.1.5 — have you routed to /v.plan yet?" -ForegroundColor Yellow
+        $warnings++
+    }
+} else {
+    Write-Host "   ⚠️  Cannot determine current phase" -ForegroundColor Yellow
+    $warnings++
+}
+
+Write-Host ""
+Write-Host "════════════════════════════════════════════════════"
+Write-Host "📊 Errors: $errors | Warnings: $warnings"
+
+if ($errors -eq 0 -and $warnings -eq 0) {
+    Write-Host "✅ PASS — .flow-state.yaml correctly updated" -ForegroundColor Green
+    exit 0
+} elseif ($errors -eq 0) {
+    Write-Host "⚠️  PASS WITH WARNINGS — check warnings above" -ForegroundColor Yellow
+    exit 0
+} else {
+    Write-Host "❌ FAIL — .flow-state.yaml needs to be updated before continuing" -ForegroundColor Red
+    exit 1
+}

package/skills/prototype/scripts/check-flow-state.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# check-flow-state.sh — Kiểm tra .flow-state.yaml đã được update sau prototype
+# Usage: ./check-flow-state.sh <feature-number>
+#        ./check-flow-state.sh 005
+#
+# Checks: artifacts.prototype.* fields tồn tại và có giá trị
+
+FEATURE_NUM="${1}"
+
+if [ -z "$FEATURE_NUM" ]; then
+  # Auto-detect từ thư mục features có prototype-notes.md
+  FEATURE_DIR=$(ls -d .v-flow/features/*/ 2>/dev/null | while read d; do
+    [ -f "${d}prototype-notes.md" ] && echo "$d" && break
+  done)
+  if [ -z "$FEATURE_DIR" ]; then
+    echo "❌ Cannot find feature directory with prototype-notes.md"
+    echo "   Usage: $0 <feature-number>  (e.g. $0 005)"
+    exit 1
+  fi
+  FLOW_STATE="${FEATURE_DIR}.flow-state.yaml"
+else
+  # Zero-pad nếu cần (005, 012, etc.)
+  PADDED=$(printf "%03d" "$FEATURE_NUM" 2>/dev/null || echo "$FEATURE_NUM")
+  FEATURE_DIR=$(ls -d .v-flow/features/${PADDED}-*/ 2>/dev/null | head -1)
+  if [ -z "$FEATURE_DIR" ]; then
+    FEATURE_DIR=".v-flow/features/${FEATURE_NUM}/"
+  fi
+  FLOW_STATE="${FEATURE_DIR}.flow-state.yaml"
+fi
+
+if [ ! -f "$FLOW_STATE" ]; then
+  echo "❌ .flow-state.yaml not found: $FLOW_STATE"
+  exit 1
+fi
+
+echo "📋 Flow State Check (prototype section): $FLOW_STATE"
+echo "════════════════════════════════════════════════════"
+ERRORS=0
+WARNINGS=0
+
+# 1. Section artifacts.prototype tồn tại
+echo ""
+echo "### 1. Prototype Section Exists"
+if grep -q "prototype" "$FLOW_STATE"; then
+  echo "   ✅ 'prototype' section found"
+else
+  echo "   ❌ No 'prototype' section in .flow-state.yaml"
+  echo "      Add: artifacts.prototype.verdict, artifacts.prototype.branch, etc."
+  ERRORS=$((ERRORS+1))
+fi
+
+# 2. Verdict đã được điền
+echo ""
+echo "### 2. Verdict Field"
+VERDICT=$(grep -A5 "prototype" "$FLOW_STATE" | grep -i "verdict" | grep -oiE "VALIDATED|REJECTED|INCONCLUSIVE|null|~|\"\"" | head -1)
+if [ -z "$VERDICT" ]; then
+  echo "   ⚠️  verdict field not found under prototype section"
+  WARNINGS=$((WARNINGS+1))
+elif echo "$VERDICT" | grep -qiE "null|~|\"\""; then
+  echo "   ❌ verdict is empty/null — prototype not yet concluded"
+  ERRORS=$((ERRORS+1))
+else
+  echo "   ✅ verdict: $VERDICT"
+fi
+
+# 3. Branch đã được điền
+echo ""
+echo "### 3. Branch Field"
+BRANCH=$(grep -A5 "prototype" "$FLOW_STATE" | grep -i "branch" | grep -oiE "LOGIC|UI|null|~|\"\"" | head -1)
+if [ -z "$BRANCH" ] || echo "$BRANCH" | grep -qiE "null|~|\"\""; then
+  echo "   ⚠️  branch field empty/missing (should be LOGIC or UI)"
+  WARNINGS=$((WARNINGS+1))
+else
+  echo "   ✅ branch: $BRANCH"
+fi
+
+# 4. Phase hiện tại có tiến sang B.0 chưa
+echo ""
+echo "### 4. Pipeline Phase"
+CURRENT_PHASE=$(grep -i "current_phase\|phase:" "$FLOW_STATE" | head -1 | grep -oE "S\.[0-9.]+|B\.[0-9.]+|R\.[0-9.]+")
+if [ -z "$CURRENT_PHASE" ]; then
+  echo "   ⚠️  Cannot determine current phase"
+  WARNINGS=$((WARNINGS+1))
+else
+  echo "   ℹ️  Current phase: $CURRENT_PHASE"
+  if [[ "$CURRENT_PHASE" == "S.1.5" ]]; then
+    echo "   ⚠️  Still at S.1.5 — have you routed to /v.plan yet?"
+    WARNINGS=$((WARNINGS+1))
+  fi
+fi
+
+echo ""
+echo "════════════════════════════════════════════════════"
+echo "📊 Errors: $ERRORS | Warnings: $WARNINGS"
+if [ "$ERRORS" -eq 0 ] && [ "$WARNINGS" -eq 0 ]; then
+  echo "✅ PASS — .flow-state.yaml correctly updated"
+  exit 0
+elif [ "$ERRORS" -eq 0 ]; then
+  echo "⚠️  PASS WITH WARNINGS — check warnings above"
+  exit 0
+else
+  echo "❌ FAIL — .flow-state.yaml needs to be updated before continuing"
+  exit 1
+fi

package/skills/prototype/scripts/check-prototype-cleanup.ps1

@@ -0,0 +1,124 @@
+# check-prototype-cleanup.ps1 — Kiểm tra prototype code đã được cleanup chưa
+# Usage: .\check-prototype-cleanup.ps1 [<feature-number>]
+#        .\check-prototype-cleanup.ps1 005
+#
+# Rule: Sau khi có verdict, thư mục prototype/ nên được xóa.
+#       Chỉ prototype-notes.md là được phép còn lại.
+
+param(
+    [string]$FeatureNum = ""
+)
+
+function Check-SingleFeature {
+    param([string]$featureDir)
+
+    $prototypeDir = Join-Path $featureDir "prototype"
+    $notesFile    = Join-Path $featureDir "prototype-notes.md"
+    $errors       = 0
+
+    Write-Host "📋 Prototype Cleanup Check: $featureDir"
+    Write-Host "══════════════════════════════════════════"
+
+    # Check 1: prototype/ còn tồn tại không
+    Write-Host ""
+    Write-Host "### 1. Prototype Directory"
+    if (-not (Test-Path $prototypeDir)) {
+        Write-Host "   ✅ prototype/ directory not found — already cleaned up" -ForegroundColor Green
+    } else {
+        if (Test-Path $notesFile) {
+            Write-Host "   ❌ prototype/ still exists after verdict was captured" -ForegroundColor Red
+            Write-Host "   Files:"
+            Get-ChildItem $prototypeDir | ForEach-Object { Write-Host "     - $($_.Name)" }
+            Write-Host ""
+            Write-Host "   → To cleanup:"
+            Write-Host "     Remove-Item -Recurse -Force '$prototypeDir'"
+            $errors++
+        } else {
+            Write-Host "   ⚠️  prototype/ exists but no prototype-notes.md yet" -ForegroundColor Yellow
+            Write-Host "      → Capture verdict first before cleanup"
+            $errors++
+        }
+    }
+
+    # Check 2: prototype-notes.md tồn tại
+    Write-Host ""
+    Write-Host "### 2. Prototype Notes (the one thing to keep)"
+    if (Test-Path $notesFile) {
+        Write-Host "   ✅ prototype-notes.md present" -ForegroundColor Green
+        $size = (Get-Item $notesFile).Length
+        if ($size -lt 200) {
+            Write-Host "   ⚠️  File is very small ($size bytes) — may be incomplete" -ForegroundColor Yellow
+            $errors++
+        }
+    } else {
+        Write-Host "   ⚠️  prototype-notes.md not found" -ForegroundColor Yellow
+        Write-Host "      → If prototype is done, create notes before deleting prototype/"
+    }
+
+    Write-Host ""
+    Write-Host "══════════════════════════════════════════"
+    Write-Host "📊 Errors: $errors"
+    if ($errors -eq 0) {
+        Write-Host "✅ PASS — prototype cleanup complete" -ForegroundColor Green
+        return 0
+    } else {
+        Write-Host "❌ FAIL — cleanup needed" -ForegroundColor Red
+        return 1
+    }
+}
+
+# ── Main ──────────────────────────────────────────────────────────
+
+if (-not $FeatureNum) {
+    # Auto-detect: scan tất cả features
+    $allFeatureDirs = Get-Item ".v-flow/features/*/" -ErrorAction SilentlyContinue
+    if (-not $allFeatureDirs) {
+        Write-Host "❌ No feature directories found under .v-flow/features/" -ForegroundColor Red
+        exit 1
+    }
+
+    $foundAny   = $false
+    $totalErrors = 0
+
+    foreach ($dir in $allFeatureDirs) {
+        $prototypeDir = Join-Path $dir.FullName "prototype"
+        $notesFile    = Join-Path $dir.FullName "prototype-notes.md"
+
+        if ((Test-Path $notesFile) -and (Test-Path $prototypeDir)) {
+            $foundAny = $true
+            Write-Host "⚠️  STALE PROTOTYPE DETECTED: $($dir.FullName)" -ForegroundColor Yellow
+            Write-Host "   prototype-notes.md exists (verdict captured) BUT prototype/ folder still present"
+            Write-Host "   Files in prototype/:"
+            Get-ChildItem $prototypeDir | ForEach-Object { Write-Host "     - $($_.Name)" }
+            Write-Host "   → Run: Remove-Item -Recurse -Force '$prototypeDir'"
+            $totalErrors++
+        } elseif ((Test-Path $prototypeDir) -and -not (Test-Path $notesFile)) {
+            $foundAny = $true
+            Write-Host "⚠️  PROTOTYPE WITHOUT NOTES: $($dir.FullName)" -ForegroundColor Yellow
+            Write-Host "   prototype/ folder exists but prototype-notes.md is missing"
+            Write-Host "   → Capture verdict first, then cleanup"
+            $totalErrors++
+        }
+    }
+
+    if (-not $foundAny) {
+        Write-Host "✅ No active prototype directories found — all clean" -ForegroundColor Green
+        exit 0
+    }
+
+    Write-Host ""
+    Write-Host "📊 Total issues: $totalErrors"
+    if ($totalErrors -gt 0) { exit 1 } else { exit 0 }
+}
+
+# Single feature mode
+$padded = $FeatureNum.PadLeft(3, '0')
+$featureDir = Get-Item ".v-flow/features/$padded-*/" -ErrorAction SilentlyContinue | Select-Object -First 1
+if (-not $featureDir) {
+    $featureDir = ".v-flow/features/$FeatureNum/"
+} else {
+    $featureDir = $featureDir.FullName
+}
+
+$exitCode = Check-SingleFeature -featureDir $featureDir
+exit $exitCode