@relipa/ai-flow-kit 0.1.2-beta.0 → 0.1.3

package/custom/skills/test-analysis/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: test-analysis
+description: Gate 1 — AI phân tích requirements từ ticket Backlog/Jira + fetch linked docs, hỏi clarify với TESTER (từng câu một), xác định scope/risks/approach, viết test-analysis.md. TESTER review và APPROVED để sang Gate 2.
+keywords: gate1, test analysis, requirement, scope, risk, approach, tester, clarify, ticket, backlog, jira
+---
+
+# Test Analysis — Gate 1
+
+> **GATE 1: Chạy đầu tiên, trước tất cả gates khác.**
+>
+> Principle: AI đọc ticket/requirements, hỏi clarify (từng câu một), xác định scope + risks + approach, viết test-analysis.md. TESTER review và APPROVED.
+
+---
+
+## Conditions to Enter Gate 1
+
+Một trong hai:
+- ✅ Ticket context tồn tại tại `.aiflow/context/current.json` (load qua `ak use TICKET-123`)
+- ✅ Tester mô tả feature cần test trực tiếp trong chat
+
+---
+
+## Steps
+
+### Step 1: Load Input
+
+1. Đọc `.aiflow/context/current.json` nếu tồn tại → lấy ticket title, description, acceptance criteria
+2. Nếu có `supplementaryContext[]` → đọc từng item (linked tickets, comments, files, docs)
+3. Nếu thấy URL backlog/jira trong description chưa được fetch → chạy `ak fetch-links <url>` và tích hợp kết quả
+4. Nếu không có context file → hỏi TESTER: "Bạn muốn test feature nào? Mô tả ngắn gọn hoặc paste ticket description."
+
+**Trigger kép:**
+- Sau `ak use TICKET-123`: AI auto-start Gate 1 — TESTER không cần gõ thêm lệnh
+- Sau `ak fetch-links <url>` (optional): AI tích hợp linked requirements trước khi phân tích
+
+---
+
+### Step 2: Phân tích Requirements
+
+Dựa trên ticket/description, phân tích:
+
+1. **Scope** — Module/màn hình/feature cụ thể đang test. Ranh giới: bao gồm gì, không bao gồm gì
+2. **Functional Analysis**:
+   - Feature Overview (mô tả tính năng)
+   - Main Flow (happy path chính)
+   - Alternative Flows (các luồng phụ)
+   - User Roles / Permissions
+   - Business Rules
+   - Validations (input/output)
+   - State / Status liên quan
+   - API / External System (nếu có)
+3. **Non-Functional Analysis**:
+   - Accessibility (WCAG, screen reader)
+   - Compatibility (Browser/Device/OS)
+4. **Risk Areas** — High-risk flows, edge cases dễ có bug
+5. **Test Approach** — Manual / Automation / Mixed + estimate số TCs
+
+---
+
+### Step 3: Clarify Q&A
+
+**Hỏi clarify khi:**
+- Acceptance criteria không đo được hoặc mơ hồ
+- Scope không rõ (in-scope vs out-of-scope)
+- Business rule có edge cases chưa được document
+- Môi trường test chưa xác định (browser, device, data)
+- Dependency với feature/ticket khác chưa rõ
+- Permission/role matrix chưa đầy đủ
+
+**Cách hỏi:** từng câu một, chờ tester trả lời trước khi hỏi tiếp.
+
+**Ví dụ:**
+> "Tester có muốn test trên mobile (iOS/Android) hay chỉ desktop browser?"
+> (chờ trả lời)
+> "Role nào có thể thực hiện action này — tất cả user hay chỉ admin?"
+
+**Khi đủ thông tin** → tiến sang Step 4 mà không cần hỏi thêm.
+
+---
+
+### Step 4: Write test-analysis.md
+
+Tạo `test-plan/test-analysis.md`:
+
+```markdown
+# Test Analysis: [Ticket ID / Feature Name]
+
+**Date:** [YYYY-MM-DD]
+**Status:** ⏸️ Waiting for TESTER Approval
+**Risk Level:** [Low / Medium / High]
+**Estimate:** [S / M / L / XL]
+
+---
+
+## 1. Scope Definition
+
+### In-Scope
+- [Module/màn hình/feature cụ thể đang test]
+- [...]
+
+### Out-of-Scope
+- [Những gì KHÔNG test trong task này]
+
+---
+
+## 2. Functional Analysis
+
+### Feature Overview
+[Mô tả tính năng — 2-3 câu]
+
+### Main Flow
+1. [Bước 1]
+2. [Bước 2]
+3. [...]
+
+### Alternative Flows
+- **Alt 1:** [Tên flow] — [Mô tả]
+- **Alt 2:** [Tên flow] — [Mô tả]
+
+### User Roles / Permissions
+| Role | Quyền | Ghi chú |
+|------|-------|---------|
+| [Role] | [Được làm gì] | [Hạn chế nếu có] |
+
+### Business Rules
+- **BR1:** [Mô tả rule]
+- **BR2:** [...]
+
+### Validations
+| Field/Action | Rule | Error Message |
+|-------------|------|---------------|
+| [Field] | [Rule] | [Message] |
+
+### State / Status
+| State | Trigger | Hành vi |
+|-------|---------|---------|
+| [State] | [Khi nào] | [Màn hình/behavior] |
+
+### API / External System
+| API | Endpoint | Mục đích |
+|-----|----------|---------|
+| [API] | [URL] | [Dùng để làm gì] |
+
+---
+
+## 3. Non-Functional Analysis
+
+### Accessibility (WCAG)
+- [ ] [Yêu cầu accessibility cụ thể]
+
+### Compatibility
+| Browser/Device | Version | Priority |
+|----------------|---------|----------|
+| Chrome Desktop | Latest | High |
+| [Other] | [...] | [...] |
+
+---
+
+## 4. Test Environment
+
+### Test Data Dependencies
+- [Data cần chuẩn bị trước khi test]
+
+### Third-party Integrations
+- [Integration cần mock hay test thật]
+
+---
+
+## 5. Requirements Clarification (Q&A)
+
+| Câu hỏi | Trả lời | Ngày |
+|---------|---------|------|
+| [Q1] | [A1] | [Date] |
+| [Q2] | [A2] | [...] |
+
+---
+
+## 6. Assumptions
+
+- [Assumption 1]
+- [Assumption 2]
+
+---
+
+## 7. Risk Areas
+
+### High-Risk Flows
+- [Flow dễ có bug — lý do]
+
+### Edge Cases cần chú ý
+- [Edge case 1]
+- [Edge case 2]
+
+---
+
+## 8. Test Approach
+
+- **Manual test cases:** [N] cases
+- **Automation (Playwright):** [N] cases
+- **Test environment:** [URL, browser, device]
+- **Test data:** [Cách chuẩn bị data]
+
+---
+
+## 9. Out of Scope
+
+- [Item 1 — lý do không test]
+- [Item 2]
+
+---
+
+## 10. Effort Estimate
+
+| Loại | Size | Ghi chú |
+|------|------|---------|
+| Gate 2 (Test Planning) | S/M/L | Khoảng [N] scenarios |
+| Gate 3 (Execution) | S/M/L | Khoảng [N] TCs |
+| Gate 4 (Report) | S | Tổng hợp kết quả |
+| **Total** | **S/M/L/XL** | |
+
+> S = <2h · M = 2–4h · L = 4–8h · XL = 8h+ (split recommended)
+```
+
+---
+
+### Step 5: Present to Tester
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️ GATE 1: TEST ANALYSIS READY
+
+Summary:
+  Scope:     [N] features / [N] flows
+  Risk:      [Low / Medium / High]
+  Approach:  [Manual / Automation / Mixed]
+  Estimate:  [S / M / L / XL]
+
+→ Review: test-plan/test-analysis.md
+→ Type APPROVED to proceed to Gate 2
+→ Or provide feedback to update
+
+⚠️ I will NOT proceed to Gate 2 until I receive "APPROVED".
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+### Step 6: Handle Feedback
+
+- Tester cung cấp feedback → cập nhật `test-analysis.md` → re-show Gate 1 prompt
+- Tester gõ `APPROVED` → tiến sang Gate 2 (`generate-testcase` skill)
+
+---
+
+## Mandatory Rules
+
+- ❌ **KHÔNG** tiến sang Gate 2 khi chưa nhận "APPROVED"
+- ❌ **KHÔNG** hỏi nhiều câu cùng lúc — từng câu một, chờ trả lời
+- ❌ **KHÔNG** viết code ở Gate 1
+- ✅ **PHẢI** lưu `test-plan/test-analysis.md`
+- ✅ **PHẢI** hiển thị Gate 1 prompt và chờ APPROVED
+- ✅ **PHẢI** xác định scope rõ ràng trước khi liệt kê flows

package/custom/templates/shared/gate-workflow.md

@@ -5,12 +5,28 @@
 
 You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
 - **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
-- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
-- Read instructions and follow the gate sequence below — NO EXCEPTIONS.
+- **AUTO-START Gate 1 immediately** — do NOT wait to be asked.
+- Read the context, **check `taskType`**, and follow the matching workflow — NO EXCEPTIONS.
 - **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
 
+### Workflow Selection
+
+Read `.aiflow/context/current.json` → check the `taskType` field:
+
+| `taskType` value | Workflow to follow |
+|---|---|
+| `testing` | **[TESTER] 4-Gate Testing Workflow** (below) |
+| `execute` | **[EXECUTE] Executing Flow** (below) |
+| `feature`, `bug-fix`, `refactor`, `investigation`, `documentation` | **[DEV] 5-Gate Development Workflow** (below) |
+
+If `taskType` is missing or unrecognized, default to the DEV workflow and ask ONE clarifying question.
+
 ---
 
+## [DEV] 5-Gate Development Workflow
+
+> **For:** `feature` · `bug-fix` · `refactor` · `investigation` · `documentation`
+
 ### GATE 1 — AI Analyze Requirement (auto-start)
 
 **INVOKE:** `read-study-requirement` skill
@@ -89,3 +105,291 @@ Only runs after Gate 4 has been APPROVED.
 Guide on creating a Pull Request with the ticket link.
 
 > **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+
+---
+
+## [TESTER] 4-Gate Testing Workflow
+
+> **For:** `testing`
+> **Interaction Rules:** Ask ONE clarifying question at a time — wait for TESTER reply before proceeding. NEVER batch questions.
+
+### GATE 1 — Phân tích & Confirm (auto-start)
+
+**INVOKE:** `test-analysis` skill
+
+1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
+2. Fetch linked docs if URLs present in description (`ak fetch-links <url>`)
+3. Analyze scope, functional flows, non-functional requirements, risks
+4. Ask clarifying questions — **ONE at a time**, wait for reply
+5. Write `test-plan/test-analysis.md`
+6. Display gate pause — wait for **APPROVED**
+
+> **Tip:** TESTER can trigger with: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+
+```
+⏸️ GATE 1: TEST ANALYSIS READY
+→ Review: test-plan/test-analysis.md
+→ Type APPROVED to proceed to Gate 2
+```
+
+> **Telemetry:** Run `ak gate 1 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+> Run `ak gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received. Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 2 — Lập Kế Hoạch Test (4 phases, each needs APPROVED)
+
+Only runs after Gate 1 APPROVED.
+
+> **Rule:** TESTER must approve each phase before AI moves to the next. Never merge phases.
+
+> **Telemetry:** Run `ak gate 2 start --ticket [ticket-id]` when starting Phase 2a. Run as-is — do NOT append shell redirects.
+
+#### Phase 2a — Scenarios & Checklist
+
+**INVOKE:** `generate-testcase` skill (Phase 2a)
+
+- If TESTER declared `PR: <url>` → **INVOKE** `pr-impact-analysis` skill (Dev Artifacts Check) first
+- Generate test scenarios/checklist TABLE covering: Happy Path, Negative, Validation, Boundary, Edge Cases, State Transitions, Role-based, Accessibility, Compatibility, Data Integrity, Integration, Exploratory
+- Save `test-plan/checklist.md`
+
+```
+⏸️ GATE 2a: SCENARIOS READY
+→ Type APPROVED to generate test cases
+```
+
+#### Phase 2b — Generate Test Cases
+
+**INVOKE:** `generate-testcase` skill (Phase 2b)
+
+- Generate detailed test cases TABLE from Phase 2a checklist: `TC_ID | Scenario | Preconditions | Test Steps | Test Data | Expected Result`
+- TC_ID format: `TC_[Module]_[NNN]` (e.g. `TC_Login_001`)
+- Expected result ONLY from ticket/spec — never from PR/dev description
+- Save `test-plan/test-cases/`
+
+```
+⏸️ GATE 2b: TEST CASES READY
+→ Type APPROVED to proceed to review
+```
+
+#### Phase 2c — Review & Optimize
+
+**INVOKE:** `generate-testcase` skill (Phase 2c)
+
+- Self-review: check duplicates, problematic TCs (vague steps, unmeasurable expected result), missing TCs, coverage gaps, accessibility/compatibility coverage
+- Output `test-plan/review-report.md` with action items
+
+```
+⏸️ GATE 2c: REVIEW COMPLETE
+→ Type APPROVED to finalize and generate scripts
+```
+
+#### Phase 2d — Coverage Check & Playwright Scripts
+
+**INVOKE:** `coverage-check` skill
+
+- Apply all action items from Phase 2c
+- Generate coverage matrix (requirement → TC IDs)
+- Export final test case set to `test-plan/test-cases/final-testcases.md`
+- **INVOKE** `automation-testing` skill → generate Playwright scripts to `test-plan/test-scripts/`
+
+```
+⏸️ GATE 2: TEST PLAN READY
+Test cases: [N] total ([N] manual / [N] automation)
+Coverage: [N]% requirements covered
+Scripts: [N] Playwright specs generated
+→ Type APPROVED to proceed to Gate 3 (execution)
+```
+
+> **Telemetry:** Run `ak gate 2 approved --ticket [ticket-id]` immediately when final APPROVED received. Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 3 — Thực Thi & Evidence
+
+Only runs after Gate 2 APPROVED.
+
+**Step 3.1 — Dev Artifacts Check (Gate 3 entry)**
+
+**INVOKE:** `pr-impact-analysis` skill — check for new commits since Gate 2. If delta found → propose TC additions → TESTER approves delta only before proceeding.
+
+**Step 3.2 — Execute Playwright**
+
+```bash
+BASE_URL=<url> npx playwright test --headed
+```
+
+**Step 3.3 — Organize Evidence**
+
+**INVOKE:** `evidence-aggregation` skill
+
+- Parse `test-results/results.json`
+- Create `evidence/TC_[ID]-[scenario]/` with screenshots + traces
+- Generate `result.md` per TC
+- Auto-draft `bugs/BUG-NNN-*.md` for failed TCs
+
+**Re-test loop** — when TESTER types `RETEST: [TC_ID]`:
+
+**INVOKE:** `retest-orchestration` skill
+- Re-run Dev Artifacts Check (detect new commits in dev fix)
+- Re-execute: `npx playwright test --grep "TC_ID_pattern" --headed`
+- Update evidence (create `run-N/` subfolder — never delete prior evidence)
+- Update bug status (RESOLVED / Still OPEN)
+
+```
+⏸️ GATE 3: EXECUTION COMPLETE
+Passed: [N] | Failed: [N] | Blocked: [N]
+Bugs: [N Critical] [N High] [N Medium] [N Low]
+→ Type APPROVED when all critical/high bugs resolved
+→ Type RETEST: [TC_ID] to re-execute
+→ Type PR: [url] to declare new dev PRs
+```
+
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 4 — Báo Cáo & Sign-off
+
+Only runs after Gate 3 APPROVED.
+
+**INVOKE:** `generate-test-report` skill
+
+1. Aggregate results from `evidence/*/result.md`
+2. Summarize bugs from `bugs/BUG-*.md` by severity
+3. Verify acceptance criteria coverage from Gate 1
+4. Determine Go / No-Go: 0 unresolved Critical = Go
+5. Write `test-plan/test-report.md`
+
+```
+⏸️ GATE 4: TEST REPORT READY
+Decision: [GO / NO-GO]
+Passed: [N/total] | Bugs unresolved: [N]
+Coverage: [N]% acceptance criteria
+→ Type APPROVED to sign off
+→ Type NO-GO: [reason] to reject release
+```
+
+> **Telemetry:** Run `ak gate 4 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+> Run `ak gate 4 approved --ticket [ticket-id]` immediately when APPROVED received. Run as-is — do NOT append shell redirects.
+
+---
+
+## [EXECUTE] Executing Flow
+
+> **For:** `execute`
+> **Entry points:** `ak execute TICKET-ID` · `ak execute ./path/to/testcases.md` · `ak execute` (manual)
+> **Interaction Rules:** Ask ONE clarifying question at a time — wait for TESTER reply before proceeding.
+
+### GATE 1 — Pre-flight & Work Plan (auto-start)
+
+**INVOKE:** `execute-flow` skill (from `custom/skills/execute-flow/SKILL.md`)
+
+Pre-flight checks (stop and report if any fail):
+0. **MCP Playwright is configured** — check `~/.claude/settings.json` (global user-level) for a `playwright` key in `mcpServers`. This is global — set once, works across all repos.
+   - If missing: ask TESTER "MCP Playwright chưa cấu hình. Tự động cài vào global settings (~/.claude/settings.json)? [Y/n]"
+   - If Y: read and update `~/.claude/settings.json` by merging the playwright entry into `mcpServers`, then instruct TESTER to **restart Claude Code** before retrying. Stop here.
+   - If n: show manual install instructions (add `playwright` to `mcpServers` in `~/.claude/settings.json`). Stop here.
+1. TC file is parseable — Section 3 has at least one TC row
+2. `ak-test/{repo}/` directory exists (or offer to scaffold it)
+3. `BASE_URL` env var is set
+4. `ak-test/{repo}/playwright.config.ts` exists (or offer to create from template)
+
+Then display work plan:
+
+```
+⏸️ GATE 1: EXECUTE FLOW READY
+TC file: [path]
+Repo: [repo]
+Screen: [ScreenID] — [Screen Name]
+BASE_URL: [url]
+→ Type APPROVED to sync scripts (Gate 2)
+```
+
+> **Telemetry:** Run `ak gate 1 start --ticket [ticket-id]` when starting. Run `ak gate 1 approved --ticket [ticket-id]` when APPROVED.
+
+---
+
+### GATE 2 — Script Sync
+
+Only runs after Gate 1 APPROVED.
+
+**INVOKE:** `script-sync` skill (from `custom/skills/script-sync/SKILL.md`)
+
+Hash-based TC↔script sync — for each TC in the file:
+- **New TC** (no matching `@tc-hash` in spec): generate Playwright test using MCP (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`). Never fabricate selectors.
+- **Changed TC** (hash mismatch): update the existing test block only.
+- **Unchanged TC** (hash matches): skip — do not touch.
+- **Manual/Blocked TC**: mark `⏭️ Untest` / `⏳ Pending` — no script generated.
+
+Output: `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts` (1 file per screen, all TCs inside)
+
+```
+⏸️ GATE 2: SCRIPT SYNC COMPLETE
+✅ New: [N] | 🔄 Updated: [N] | ⏭️ Skipped: [N] | ⚠️ Manual: [N]
+→ Type APPROVED to execute (Gate 3)
+```
+
+---
+
+### GATE 3 — Execute & Evidence
+
+Only runs after Gate 2 APPROVED.
+
+**Step 3.1 — Determine run number**
+
+Check `ak-test/{repo}/results/{screenId}/` — next run is `run-{N+1}`.
+
+**Step 3.2 — Execute Playwright**
+
+```bash
+BASE_URL=<url> npx playwright test scripts/{screenId}/{ScreenID}.spec.ts
+```
+
+**Step 3.3 — Organize evidence** into `ak-test/{repo}/results/{screenId}/run-{N}/`:
+- Per-TC folder `{TC_ID}-{scenario}/` with `step-NN-{desc}.png`, `trace.zip`, `result.md`
+- Auto-draft `bugs/BUG-NNN-{slug}.md` for failed TCs
+
+**Step 3.4 — Update TC file** R1/R2 columns:
+- `✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`
+
+**Re-test loop** — when TESTER types `RETEST: [TC_ID]`:
+- Re-run Dev Artifacts Check if PR was declared
+- Re-execute only the specified TCs
+- Create new `run-{N}/` — never delete prior runs
+- Update R1/R2 columns
+
+```
+⏸️ GATE 3: EXECUTION COMPLETE
+Run: run-{N} | Passed: [N] | Failed: [N] | Untest: [N] | Pending: [N]
+→ Type APPROVED when all Critical/High bugs resolved
+→ Type RETEST: [TC_ID] to re-execute specific TCs
+→ Type PR: [url] to declare a dev fix PR
+```
+
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting. Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 4 — Report & Bug Logging
+
+Only runs after Gate 3 APPROVED.
+
+**Step 4.1** — Generate `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md`:
+- Per-module rows with Pass/Fail/Untest/Pending counts, R1/R2 columns, % completion
+- Go/No-Go: 0 unresolved Critical = Go
+
+**Step 4.2** — Bug logging: for each `❌ Fail` TC, ask TESTER ONE at a time:
+> "BUG-NNN — [TC_ID]: [title]. Log to Jira? (Y/N/edit)"
+
+Wait for reply before moving to next bug.
+
+```
+⏸️ GATE 4: REPORT READY
+Decision: [GO / NO-GO]
+Bugs logged: [N] | Skipped: [N]
+→ Review: ak-test/{repo}/results/{screenId}/run-{N}/testreport.md
+→ Type APPROVED to sign off
+```
+
+> **Telemetry:** Run `ak gate 4 start --ticket [ticket-id]` when starting. Run `ak gate 4 approved --ticket [ticket-id]` when APPROVED.

package/docs/common/CHANGELOG.md

@@ -7,6 +7,90 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.1.3] - 2026-06-18
+
+### Added
+
+- **`execute` task type — 4-Gate Executing Flow** — New end-to-end test execution workflow for QA testers. Activated when `taskType: "execute"` in context. Orchestrated by the new `execute-flow` skill across 4 gates:
+  - **Gate 1 — Pre-flight & Work Plan**: Validates TC file, `ak-test/{repo}/` directory, `BASE_URL` env var, and `playwright.config.ts` before any scripts are touched.
+  - **Gate 2 — Script Sync**: Hash-based TC↔script sync via the new `script-sync` skill. Each TC is hashed as `SHA1(TC_ID + "|" + Steps + "|" + Expected Result)[:8]` and compared against the `@tc-hash` comment in the spec file. New TCs get scripts generated via MCP browser tools; changed TCs update their existing block; unchanged TCs are skipped entirely.
+  - **Gate 3 — Execute & Evidence**: Runs `npx playwright test` and organizes evidence into `ak-test/{repo}/results/{screenId}/run-{N}/` with per-TC folders (screenshots, trace.zip, result.md). Auto-drafts bug files for failed TCs. Supports `RETEST: [TC_ID]` loop.
+  - **Gate 4 — Report & Bug Logging**: Generates `testreport.md` with Go/No-Go decision; logs each failed TC to Jira/Backlog one-by-one with interactive confirm per bug.
+
+- **`execute-flow` skill** (`custom/skills/execute-flow/SKILL.md`) — 4-gate execute flow orchestrator. Handles 3 entry points: `ak execute TICKET-ID` (ticket with `taskType: "execute"`), `ak execute ./path/to/testcases.md` (direct TC file), and `ak execute` (manual — AI asks for TC file). Output structure: `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts` for scripts; `ak-test/{repo}/results/{screenId}/run-{N}/` for evidence.
+
+- **`script-sync` skill** (`custom/skills/script-sync/SKILL.md`) — Hash-based TC↔Playwright script sync engine. Called from execute-flow Gate 2. Never fabricates selectors — uses MCP browser tools (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`) for any new/changed TC. Produces one `.spec.ts` per screen with all TCs inside, using `screenId` (lowercase) for directory paths and `{ScreenID}.spec.ts` (uppercase) for the filename.
+
+- **`playwright.config.ts` template** for execute-flow (`custom/skills/execute-flow/templates/playwright.config.ts`) — Default config for each `ak-test/{repo}` repo with HTML + JSON reporters, screenshot-on-failure, and trace-on-failure. AI offers to scaffold this file during Gate 1 pre-flight if it doesn't exist.
+
+- **`execute` entry in `gate-workflow.md` Workflow Selection table** — `gate-workflow.md` (single source of truth for all AI agent instruction files) now routes `taskType: "execute"` to the `[EXECUTE] Executing Flow` section. Distributed to all agents (Claude, Gemini, Cursor, Copilot) via `ak init` / `ak up`.
+
+- **`▶️ Execute Test` option in `ak use` type selector** — Both the `promptForTaskType()` shared function (Backlog/Jira loaders) and the `manualContext()` manual entry flow now include `execute` as a selectable type. Users can run `ak use --manual` or `ak use TICKET-ID` and choose "Execute Test" to route the AI to the execute-flow.
+
+- **`ak execute` command** (`ak ex` alias) — New top-level CLI entry point that bypasses `ak use`. Accepts a ticket ID, a TC file path, or no argument (AI asks interactively). Documented in README, QUICK_START, cli-reference, and `ak guide --commands`.
+
+- **`test-analysis` skill** (`custom/skills/test-analysis/SKILL.md`) — Gate 1 analysis skill for the [TESTER] workflow. Reads ticket context, fetches linked docs, analyzes scope and risk, asks clarifying questions one at a time, and writes `test-plan/test-analysis.md`.
+
+- **`coverage-check` skill** (`custom/skills/coverage-check/SKILL.md`) — Gate 2d skill that applies review action items, generates a requirement→TC coverage matrix, exports the final test case set to `test-plan/test-cases/final-testcases.md`, and invokes `automation-testing` to generate Playwright scripts.
+
+- **`evidence-aggregation` skill** (`custom/skills/evidence-aggregation/SKILL.md`) — Parses `test-results/results.json`, organizes screenshots and traces into `evidence/TC_[ID]-[scenario]/` folders, generates per-TC `result.md`, and auto-drafts `bugs/BUG-NNN-*.md` for failed TCs.
+
+- **`retest-orchestration` skill** (`custom/skills/retest-orchestration/SKILL.md`) — Handles the `RETEST: [TC_ID]` loop in Gate 3. Re-runs dev artifacts check (detect new commits), re-executes only specified TCs, creates `run-N/` subfolders (never deletes prior evidence), and updates bug status.
+
+- **`pr-impact-analysis` skill** (`custom/skills/pr-impact-analysis/SKILL.md`) — Checks for new commits/PRs between gates to ensure TC coverage stays current with dev changes.
+
+- **`log-bug` skill** (`custom/skills/log-bug/SKILL.md`) — Logs a failed TC as a bug ticket in Jira/Backlog with structured fields (severity, steps, expected/actual, evidence link).
+
+- **Playwright harness scaffold** — `ak scaffold playwright` (via `scripts/scaffold-playwright.js`) creates the `ak-test/{repo}/` directory structure with `playwright.config.ts`, `tests/e2e/fixtures/test.ts`, `tests/e2e/pages/BasePage.ts`, `tests/e2e/support/auth.ts`, and `.env.example`. Covered by 90-line Jest test suite in `tests/scaffold-playwright.test.js`.
+
+- **Playwright MCP preset** (`custom/mcp-presets/playwright.json`) — MCP configuration preset for browser automation tools used by `script-sync` during TC→script generation.
+
+- **`test-patterns.md` rules file** (`custom/rules/test-patterns.md`) — Team-level Playwright patterns and conventions referenced by `automation-testing` and `script-sync` skills.
+
+- **`generate-testcase` skill — Phase 2a/2b/2c structure** — Skill rewritten with explicit phased execution: Phase 2a (scenarios & checklist), Phase 2b (generate detailed TC table), Phase 2c (review & optimize). TC_ID format: `TC_[Module]_[NNN]`. Gate pauses after each phase.
+
+- **`automation-testing` skill — MCP browser integration** — Updated to document MCP tool sequence (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`) for generating reliable Playwright locators without fabricating selectors.
+
+### Fixed
+
+- **`execute-flow` Gate 1 pre-flight missing `playwright.config.ts` check** — Original Gate 1 had 3 checks; spec required 4. Added explicit check for `ak-test/{repo}/playwright.config.ts` with offer to scaffold from template.
+- **`screenId` casing ambiguity in execute-flow/script-sync** — Directory paths use lowercase `screenId` (e.g. `ad10`); spec file names remain uppercase `{ScreenID}.spec.ts` (e.g. `AD10.spec.ts`). Both skills now explicitly document this distinction with examples to prevent AI from using wrong case.
+- **`--reporter` CLI flag overriding config reporters** — Gate 3 run command previously included `--reporter=json,html` which overrides (not appends) reporters defined in `playwright.config.ts`, causing the HTML report to be replaced entirely. Removed the flag; reporters are now defined solely in `playwright.config.ts`.
+
+---
+
+## [0.1.2] - 2026-06-13
+
+### Added
+
+- **`python-ml` framework type** — New framework option for Python ML projects (scikit-learn / PyTorch / TensorFlow / Keras / MLflow / Wandb). Auto-detected from `requirements.txt` or `pyproject.toml` when any of the following dependencies are found: `torch`, `scikit-learn`, `sklearn`, `tensorflow`, `keras`, `mlflow`, `wandb`. Uses a dedicated gate workflow (`ml-gate-workflow.md`) tailored for ML iteration cycles (experiment → evaluate → iterate) instead of the standard software-development gate workflow. Select via `ak init` checkbox or `ak init -f python-ml`.
+- **Task type selector in `ak use`** — After loading a ticket from Backlog, Jira, a local file, or manual entry, `ak use` now prompts the developer to confirm or change the task type via an interactive list (Bug Fix, Feature, Investigation, Refactor, Impact Analysis, Documentation). The type is auto-detected from the ticket title/issue type first and pre-selected as the default. The chosen value is saved to `.aiflow/context/current.json` as `taskType` and is available to the gate workflow throughout the session.
+- **Telemetry warning on `ak use`** — If telemetry logging is not yet enabled, `ak use` now prints a yellow warning at startup so developers know their activity is not being tracked:
+  ```
+  ⚠  Telemetry logging is not enabled. Developer activity will not be tracked.
+     Run: ak telemetry enable  to set up team productivity tracking.
+  ```
+  The check is wrapped in try/catch and never blocks the command. Silently skipped when telemetry is already enabled.
+- **Backup before overwrite (`aiflow update` / `aiflow init`)** — Before overwriting any AI instruction file (CLAUDE.md, GEMINI.md, `.cursorrules`, `.github/copilot-instructions.md`), the current file is now backed up to `.aiflow/bk/YYYY-MM-DD_HH-MM_<filename>`. Multiple backups accumulate across runs, providing a full history to roll back to.
+- **Single upfront confirm on update** — Instead of asking per-file, `aiflow update` and `aiflow init` now show a single summary of all files that will be overwritten, then ask for one confirmation before proceeding. This replaces the per-file prompt sequence that was easy to accidentally skip.
+
+### Changed
+
+- **Framework conventions included in single-framework CLAUDE.md** — Previously, the framework template (e.g. Spring Boot coding standards, architecture rules) was only appended to CLAUDE.md in multi-framework projects. Single-framework projects got only the tool header + skill registry + gate workflow, losing all stack-specific conventions. The framework template is now always embedded for single-framework setups.
+- **`aiflow update` no longer wipes `.claude/` directory** — Previously `update` called `fs.emptyDir('.claude/')` which deleted `.claude/settings.json`, destroying the SessionStart/SessionEnd/PreToolUse hooks configuration. Update now empties only `.claude/skills/` and re-copies skills there, leaving `settings.json` and other files untouched.
+
+### Fixed
+
+- **Critical: `aiflow update` / `aiflow init` did not update CLAUDE.md or GEMINI.md** — Three compounding root causes:
+  1. Old `state.json` wrote `framework: "spring-boot"` (singular string). New code read `state.frameworks` (plural array), got `undefined`, fell back to `[]`, and never called `setupFramework` — so no AI instruction file was ever written or updated.
+  2. `aiflow init` called `setupFramework` without `force: true`, triggering per-file interactive prompts. Users who pressed No (or were surprised by the overwrite prompt) silently skipped the update.
+  3. `aiflow update`'s old per-file confirm dialogs caused the same silent skip.
+  All three are fixed: singular→plural fallback added everywhere `state.frameworks` is read; both `init` and `update` now use `force: true`; the update path is backup-then-overwrite.
+- **Stale skill registry paths in CLAUDE.md** — After upgrading the package, CLAUDE.md still referenced `.aiflow/versions/0.1.1/skills/...` instead of the current `.claude/skills/...` paths. This caused Claude to fail when trying to load skills. Fixed as part of the forced-overwrite update flow above.
+- **`state.framework` (singular) not recognized after upgrade** — `aiflow update`, `aiflow init` re-run, and `ak sync-skills` all read `state.frameworks` (plural). Projects initialized before the plural key was introduced had only `framework: "spring-boot"` in state.json, causing the framework to be silently dropped and `setupFramework` to never run. Fixed with a fallback: `state.frameworks || (state.framework ? [state.framework] : [])` in `update.js`, `init.js`, and `aiflow.js`.
+
+---
+
 ## [0.1.1] - 2026-06-08
 
 ### Added