@relipa/ai-flow-kit 0.2.0 → 0.2.2-beta.0

package/custom/templates/spring-boot.md

@@ -1,224 +1,5 @@
-# Spring Boot AI System Prompt
-
-You are an expert Java Spring Boot developer. Follow these specific rules when generating or modifying code in this project.
-
-> **Code examples:** See `.rules/java/spring-boot-examples.md` — read it when generating code for a specific layer.
-
----
-
-## Project Stack
-
-- **Java:** 17+
-- **Spring Boot:** 3.x
-- **Build Tool:** Maven (prefer) or Gradle
-- **ORM:** Spring Data JPA + Hibernate
-- **Database:** MySQL / PostgreSQL
-- **Testing:** JUnit 5 + Mockito + AssertJ
-- **Utilities:** Lombok, MapStruct
-- **API Style:** RESTful JSON
-
----
-
-## Architecture
-
-Follow strict **Layered Architecture**:
-
-```
-Controller (HTTP layer)
-    ↓
-Service (Business logic)
-    ↓
-Repository (Data access - Spring Data JPA)
-    ↓
-Entity / Domain Model
-```
-
-### Package Structure
-
-```
-com.company.project/
-├── controller/         # \@RestController — HTTP endpoints only
-├── service/
-│   ├── impl/           # \@Service — business logic implementation
-│   └── [Interface].java
-├── repository/         # \@Repository — extends JpaRepository
-├── entity/             # \@Entity — JPA entities
-├── dto/
-│   ├── request/        # Input DTOs (e.g. CreateUserRequest)
-│   └── response/       # Output DTOs (e.g. UserResponse)
-├── mapper/             # MapStruct mappers (Entity ↔ DTO)
-├── exception/
-│   ├── GlobalExceptionHandler.java  # \@RestControllerAdvice
-│   └── [CustomException].java
-├── config/             # \@Configuration classes
-└── util/               # Pure utility helpers (stateless)
-```
-
----
-
-## Controller Rules
-
-- Annotate with `\@RestController` + `\@RequestMapping`
-- **Only** handle HTTP concerns: parse request, call service, return response
-- Never put business logic in Controller
-- Always use DTOs — never expose Entity directly
-- Use `ResponseEntity<T>` for explicit HTTP status control
-- Validate input with `\@Valid` + Bean Validation annotations
-
----
-
-## Service Rules
-
-- Always define an **interface**, implement in the `impl/` package
-- Annotate implementation with `\@Service`
-- All business logic lives here
-- Use `\@Transactional` at the method level (not class level)
-- Throw specific custom exceptions, not generic `RuntimeException`
-- Never return an Entity — always convert to DTO via Mapper
-
----
-
-## Repository Rules
-
-- Extend `JpaRepository<Entity, ID>`
-- Use **method name queries** for simple queries
-- Use `\@Query` (JPQL) for complex queries — avoid native SQL unless necessary
-- Never add business logic here
-- Use `\@EntityGraph` to solve N+1 problems
-
----
-
-## Entity Rules
-
-- Use Lombok: `\@Getter`, `\@Setter`, `\@NoArgsConstructor`, `\@AllArgsConstructor`, `\@Builder`
-- Avoid `\@Data` on entities (causes issues with `equals/hashCode` + lazy loading)
-- Always use `\@Table(name = "snake_case_table_name")`
-- Use `\@Column(name = "snake_case_column_name")` explicitly
-- For soft delete: add `deleted` boolean + `deletedAt` timestamp
-- Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
-
----
-
-## DTO Rules
-
-- Use separate DTOs for **Request** and **Response** — never share
-- Use Lombok: `\@Getter`, `\@Builder`, `\@AllArgsConstructor`, `\@NoArgsConstructor`
-- Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
-- Never expose internal fields (password hash, audit timestamps) in the Response DTO
-
----
-
-## MapStruct Mapper Rules
-
-- Use `\@Mapper(componentModel = "spring")` — inject as a Spring bean
-- Define explicit mappings with `\@Mapping` when field names differ
-- Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
-
----
-
-## Exception Handling
-
-- Create custom exceptions extending `RuntimeException`
-- Handle all exceptions in one `\@RestControllerAdvice` class
-- Return a consistent error response format
-- Never expose stack traces to the client
-
----
-
-## Testing Rules
-
-### Unit Tests (Service layer)
-- Test class: `[ServiceImpl]Test.java`
-- Mock all dependencies with `\@ExtendWith(MockitoExtension.class)` + `\@Mock`
-- Test happy path + edge cases + exception scenarios
-- Use AssertJ: `assertThat(result).isEqualTo(expected)`
-
-### Integration Tests (Controller layer)
-- Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
-- Test full HTTP flow with `MockMvc`
-- Use `\@Sql` or Testcontainers for database state
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Class | PascalCase | `UserService`, `OrderController` |
-| Method | camelCase | `findById`, `createOrder` |
-| Variable | camelCase | `userResponse`, `orderId` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
-| Package | lowercase | `com.company.project.service` |
-| DB Table | snake_case | `user_orders`, `product_items` |
-| DB Column | snake_case | `created_at`, `user_id` |
-| REST endpoint | kebab-case | `/api/v1/user-profiles` |
-| Request DTO | `[Action][Resource]Request` | `CreateOrderRequest` |
-| Response DTO | `[Resource]Response` | `OrderResponse` |
-
----
-
-## API Design
-
-- Version all APIs: `/api/v1/...`
-- Use plural nouns for resources: `/users`, `/orders`
-- HTTP methods: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial), `DELETE`
-- Return `201 Created` for POST, `200 OK` for GET/PUT/PATCH, `204 No Content` for DELETE
-- Use consistent pagination: `?page=0&size=20&sort=createdAt,desc`
-
-```
-GET    /api/v1/users              → 200 list
-POST   /api/v1/users              → 201 created
-GET    /api/v1/users/{id}         → 200 or 404
-PUT    /api/v1/users/{id}         → 200 or 404
-DELETE /api/v1/users/{id}         → 204 or 404
-GET    /api/v1/users/{id}/orders  → 200 nested resource
-```
-
----
-
-## Performance Rules
-
-- Always use pagination — never return unbounded lists
-- Avoid N+1: use `\@EntityGraph` or `JOIN FETCH` in JPQL
-- Add database indexes on frequently queried columns
-- Use `\@Transactional(readOnly = true)` on read-only service methods
-- For heavy read operations, consider projection interfaces
-
----
-
-## Security Rules
-
-- Never log passwords, tokens, or sensitive PII
-- Hash passwords with BCrypt: `passwordEncoder.encode(rawPassword)`
-- Validate and sanitize all user inputs via Bean Validation
-- Use `\@PreAuthorize` for method-level security
-- Never return stack traces to API consumers
-- Store secrets in environment variables / Vault — never in code
-
----
-
-## Logging Rules
-
-- Use SLF4J with Lombok `\@Slf4j`
-- `log.info` — normal business events
-- `log.warn` — recoverable issues (not found, validation fail)
-- `log.error` — unexpected exceptions (always include `ex` as the second argument)
-- Never log sensitive data (password, credit card, token)
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ `\@Autowired` field injection → use constructor injection (Lombok `\@RequiredArgsConstructor`)
-- ❌ `\@Data` on JPA entities → use `\@Getter \@Setter` separately
-- ❌ Returning `Entity` directly from Controller → always use DTO
-- ❌ `SELECT *` or unbounded `findAll()` → always paginate
-- ❌ Business logic in Controller → move to Service
-- ❌ Catching and swallowing exceptions → handle properly or rethrow
-- ❌ `new RuntimeException("something")` → create a specific custom exception
-- ❌ Hardcoding config values → use `\@Value` or `\@ConfigurationProperties`
-- ❌ `\@Transactional` on Controller → only on Service methods
-
----
-
-When explaining changes, refer to the [Spring Boot Official Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) and [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/) conventions.
+# Spring Boot AI System Prompt
+
+You are an expert Java Spring Boot developer. Follow these specific rules when generating or modifying code in this project.
+
+> **Rules & code examples:** Read `.rules/java/spring-boot-rules.md` (architecture, layer rules, naming, security, anti-patterns) and `.rules/java/spring-boot-examples.md` (code samples per layer) **in full** before writing or modifying any Java code in this project.

package/docs/common/CHANGELOG.md

@@ -7,17 +7,17 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [0.2.2] - 2026-08-06
+## [Unreleased]
 
-### Added
+## [0.2.2] - 2026-08-24
 
-- **`ak gate <n> skip --ticket <id> [--reason <text>]`** — a gate can now close as "skipped" (legitimately produced no deliverable) instead of only `start`/`approved`. First consumer: `ingest-data` Gate 3, when the AI decides the ingested content is reference-only and no task list is needed — it now runs `ak gate 3 skip` instead of leaving the gate untouched. `scripts/task.js`'s `updateTaskGateState()` gained a `skip` branch that records `skippedGates[gate] = {at, reason}` in `task-state.json` and advances `currentGate` exactly like `approved` does, so every existing "is this task done" check (which only ever inspects `currentGate`) keeps working with zero changes. Prompted by an impact assessment for the `ai-flow-ex` VS Code extension's dashboard, which was showing skipped-Gate-3 ingest-data tasks stuck as "ready to run Gate 3" forever — see `docs/superpowers/specs/2026-08-06-ingest-data-gate3-skipped-state-design.md` in `ai-flow-ex` for the paired UI-side change (reads `skippedGates` to render a distinct "⏭ Skipped" badge instead of the generic "✓ Approved").
+### Changed
 
-### Fixed
+- **`execute-test` flow (`execute-flow` + `script-sync` skills) no longer uses an `ak-test/` working dir at all — everything, including binary evidence, now lives inside `AK-Docs/03.Testing/`.** Previously the whole flow (Playwright scripts, per-TC `result.md`, bug drafts, `testreport.md`, and evidence) lived under `ak-test/{repo}/`, outside the project's docs tree — reports/bugs/scripts had no place in version control alongside the rest of `AK-Docs/03.Testing/` (Testcases, Reports, Bugs). New mapping: `05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts` (Gate 2), `04.Evidence/{repo}/{featureDir}/run-{N}/` (Gate 3, screenshots/video/`trace.zip`/raw `results.json`), `02.Reports/{repo}/{featureDir}/run-{N}/{result.md, testreport.md}` (Gate 3/4), `06.Bugs/{repo}/{featureDir}/run-{N}/BUG-NNN-*.md` (Gate 3) — this restores `docs/common/Testing-Structure.md`'s original Gate 3 → `04.Evidence/` mapping instead of diverging from it (an earlier iteration of this change had evidence live in `ak-test/` to keep binaries out of AK-Docs entirely; superseded before release in favor of `.gitignore`). `05.Scripts/` is a self-contained, runnable Playwright project (`package.json`/`node_modules`/`tsconfig.json`) living inside AK-Docs — Gate 1 auto-scaffolds it and appends `03.Testing/04.Evidence/` plus `03.Testing/05.Scripts/**/{node_modules,test-results,playwright-report,blob-report}` to `.gitignore` if missing, so the binary evidence and Playwright build artifacts never get committed even though they're colocated with the rest of the docs tree. `playwright.config.ts`'s `outputDir`/JSON reporter path read `EVIDENCE_DIR` (set by the AI per run to the `04.Evidence/` path, a simple 1-level-up relative path from `05.Scripts/` since both now live under the same `03.Testing/` parent) so each run gets its own evidence folder.
 
-- **`ak task next` treated `ingest-data` as a 2-gate flow** — a stale assumption left over from before Gate 3 (task creation & ticket generation) was added to `ingest-data` earlier in the same release cycle. `scripts/task.js` grouped it with `gen-doc`/`create-system-requirement` (`maxGate = 2`), so pausing via `ak task next` on Gate 2 would prematurely mark the task `status: 'done'` and `gateLabel(3, 'ingest-data')` returned `'Done'` instead of `'Sinh Task & Tạo Ticket'`. Split into its own 3-gate branch (`maxGate = 3`); `gen-doc`/`create-system-requirement` are unaffected.
+- **`execute-flow`/`script-sync` gained explicit DOM-assertion and evidence-quality rules** to fix reported false pass/fail results and low-quality screenshots: locators that match more than one element are now called out as the primary root cause of mis-graded TCs (fix: scope to the right container or use `data-testid`, not `.first()`/broad CSS); assertions must check the actual Expected Result content (`toHaveText`/`toBeDisabled`/etc.), not just element presence; negative/validation TCs need an assertion on the actual blocking behavior, not "page didn't crash." New shared helper `custom/skills/execute-flow/templates/evidence-helper.ts` (copied once to `AK-Docs/03.Testing/05.Scripts/Shared/`) provides `waitForUiSettled()` (networkidle + no loading indicator + fonts ready — fixes screenshots taken mid-spinner), `highlightElement()`/`removeHighlight()` (red 3px outline around the item to confirm), and `captureStepEvidence()`/`openAndCapture()` (per-TC-Step screenshot, click-to-open-modal before capturing, `scrollIntoViewIfNeeded()` for scrollable content) — every generated spec must use these instead of ad-hoc screenshot calls. `playwright.config.ts` template gained `deviceScaleFactor: 2` and a configurable `locale` (default `ja-JP`) for sharper, correctly-rendered Kanji/Katakana text in evidence, plus 1 retry to absorb timing flakes before a TC is reported FAIL.
 
-## [0.2.1] - 2026-08-05
+## [0.2.1] - 2026-08-17
 
 ### Added
 
@@ -30,6 +30,24 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - Approved tickets get their link written back into the originating `Meetings-Log`/`QnA-Log`/`Confirmations-Log` entry (`→ Tasks created: TICKET-101 (coding), ...`), keeping the traceability chain from PM Workflow §6 intact end-to-end.
   - **Still open, tracked in the PM Workflow doc's Vấn đề 5 implementation note:** no fixed feedback→task-type rule table (AI still judges per-context); new tickets don't auto-attach `functionId`/labels (Dev/BA/QA still assign on `ak use TICKET-XXX`); Backlog issueType/priority default to the project's first issueType and a "Normal"-named priority unless overridden explicitly in the task JSON.
 
+- **`ak gate <n> skip --ticket <id> [--reason <text>]`** — a gate can now close as "skipped" (legitimately produced no deliverable) instead of only `start`/`approved`. First consumer: `ingest-data` Gate 3, when the AI decides the ingested content is reference-only and no task list is needed — it now runs `ak gate 3 skip` instead of leaving the gate untouched. `scripts/task.js`'s `updateTaskGateState()` gained a `skip` branch that records `skippedGates[gate] = {at, reason}` in `task-state.json` and advances `currentGate` exactly like `approved` does, so every existing "is this task done" check (which only ever inspects `currentGate`) keeps working with zero changes. Prompted by an impact assessment for the `ai-flow-ex` VS Code extension's dashboard, which was showing skipped-Gate-3 ingest-data tasks stuck as "ready to run Gate 3" forever — see `docs/superpowers/specs/2026-08-06-ingest-data-gate3-skipped-state-design.md` in `ai-flow-ex` for the paired UI-side change (reads `skippedGates` to render a distinct "⏭ Skipped" badge instead of the generic "✓ Approved").
+
+### Changed
+
+- **Per-framework rule sections (Architecture, layer rules, naming, security, anti-patterns) moved out of `CLAUDE.md`/`AGENTS.md` into `.rules/<lang>/<framework>-rules.md`, alongside the existing `-examples.md`.** Extends the same on-demand `.rules/` pattern already used for code samples to the rules themselves: `custom/templates/<framework>.md` now holds only the title, a one-line intro, and a single "> **Rules & code examples:**" pointer to both files — everything else (Controller/Service/Repository/Entity/DTO/Mapper/Exception/Testing/Naming/API/Performance/Security/Logging/anti-patterns, per framework) lives in the new `-rules.md` file. Applied to all 9 templates that had this structure (`spring-boot`, `php`, `php-plain`, `reactjs`, `nestjs`, `nodejs-express`, `python`, `python-django`, `python-fastapi`, `python-ml`) — `nextjs`/`vue-nuxt`/`laravel` were already ~15 lines with no such structure and are untouched. Unlike the workflow-file pointer (read once at a clear Gate-start trigger), these rules apply continuously across every code edit in Gate 3, so `custom/templates/shared/gate-workflow.md` and `ml-gate-workflow.md` both gained an explicit bullet at the top of their Gate 3 (`Code Generation` / `Implement, Train & Iterate`) step: read the rules + examples files pointed to at the top of `CLAUDE.md`/`AGENTS.md` before the first line of code, and keep applying them to every subsequent edit, not just the first. Also fixed `generateSkillNameList()`'s "Codex indexes these automatically" wording, which became inaccurate once `claude` also uses the compact skill list (see previous entry) — reworded to name neither tool specifically. Measured on the kit's own dogfood skill set: solo `spring-boot`/`reactjs`/`php` 247/211/~205 → **41 lines each**; multi `spring-boot`+`php` 385 → **55 lines**.
+
+- **`CLAUDE.md` now uses the same compact skill list as `AGENTS.md`, and 2 techstack templates dropped a redundant "Project Stack" section.** `AI_TOOL_SKILL_LIST_STYLE` gained `'claude': 'compact'` — Claude Code auto-discovers each skill's name + description from `.claude/skills/*/SKILL.md` frontmatter on its own (same mechanism the original Codex-only rationale assumed only Codex had), so restating the full description table in `CLAUDE.md` was duplicating information the tool already surfaces natively. `custom/templates/spring-boot.md` and `reactjs.md` also dropped their "## Project Stack" bullet list (Java/Spring Boot/Maven version pins, React/TypeScript/Vite/Router/etc.) — for spring-boot every item was already restated in a more specific rule section further down (Testing Rules, Entity Rules, Mapper Rules...); for reactjs most items were too (State Management, Form, Styling, API Layer Rules), except **Router (React Router v6), the shadcn/ui pairing with Tailwind, and Vitest as the specific test runner**, which had no other home in the file and are now gone rather than relocated — worth restoring into an existing rule section later if that specificity is missed. Measured on the kit's own dogfood skill set (~46 skills): solo `spring-boot` 306 → 247 lines, solo `reactjs` ~264 → 211 lines, multi `spring-boot`+`php` 444 → 385 lines.
+
+- **`CLAUDE.md` now uses the pointer layout too, not just `AGENTS.md`.** `AI_TOOL_LAYOUT` in `scripts/init.js` gained `'claude': 'pointer'` alongside the existing `'codex': 'pointer'` — CLAUDE.md is loaded in full at the start of every session regardless of which gate (if any) is active, so inlining the ~115 KB DEV/TESTER/EXECUTE/gen-doc/ingest-data + BA + QA workflow set spent context on gates most sessions never touch. The workflow bodies now live in `.aiflow/instructions/` and CLAUDE.md just links to them, same as Codex. Unlike Codex's pointer layout, the skill registry keeps its full description table for `claude` (`resolveSkillListStyle()`/`resolveSkillsRoot()`) — Claude Code has no skill index of its own the way Codex does, so only the workflow bodies move out, not the registry.
+- **Techstack rule templates (`custom/templates/<framework>.md`) no longer inline full code samples for every layer.** Following the pattern already used for `spring-boot.md`/`custom/rules/java/spring-boot-examples.md`, the same split was applied to the other 9 templates that had grown a "✅ Good / ❌ Bad" code block per rule area: `reactjs`, `php`, `php-plain`, `python-ml`, `nestjs`, `nodejs-express`, `python`, `python-django`, `python-fastapi`. Each template keeps its bullet rules, naming table, and anti-pattern list, with a one-line pointer to a new `custom/rules/<lang>/<framework>-examples.md` file holding the actual code samples — read on demand when generating code for that specific layer instead of being inlined into every session's context. `FRAMEWORK_LANGUAGE` in `scripts/init.js` also gained entries for `nodejs-express`, `python`, `python-django`, `python-fastapi`, and `php-plain` (previously missing, so `.rules/<lang>/` was never copied into projects using those frameworks).
+- **Multi-framework projects no longer duplicate the tool header, skill registry, and workflow-files pointer once per framework.** A project with 2+ frameworks (e.g. a `spring-boot` backend + a `reactjs` frontend) calls `setupFramework()` once per framework with `multi: true`; each call used to emit a fully self-contained block (tool header + full skill registry + framework rules + "Installed workflow files" pointer note), so all three non-framework-specific sections got repeated verbatim per framework — the ~46-skill registry was the dominant cost in `CLAUDE.md` once the per-framework code samples above were split out. `setupFramework()` now builds all three via `buildSharedBlock()` once and writes it under its own fixed `<!-- aiflow-kit-start:shared -->` marker; per-framework blocks (`buildToolBlock(tool, ..., { includeShared: false })`) carry only the framework-specific rules and (for inline tools) the inlined gate-workflow body. The "Installed workflow files" note moved to the shared block because its 3 listed paths (`.aiflow/instructions/gate-workflow.md`, `create-spec-workflow.md`, `create-testcase-workflow.md`) are always the same 3 filenames regardless of framework — only their on-disk *content* varies per framework (e.g. ML vs standard gate workflow), not the pointer text itself. Re-running for an already-present framework upserts its block in place (new `upsertMarkerBlock()` helper) instead of appending another copy. Single-framework projects are unaffected (`includeShared` defaults to `true`, same single block as before). Measured on the kit's own dogfood project (spring-boot + php, ~46 real skills): 452 → 444 lines.
+
+- **QnA-Log table (`skill-ba-qna-template-v1.md`) gained 3 response-tracking columns — Người trả lời, Ngày trả lời, Nguồn.** `skill-ba-qna-v1.md`'s Bước 4 now spells out how each is filled: **Người trả lời** defaults to `git config user.email` (fallback `user.name`) of whoever is running the session, overridden only when the BA explicitly names a different responder (e.g. answering on the customer's behalf); **Ngày trả lời** is stamped automatically from the current system date (`dd/mm/yyyy`), never asked; **Nguồn** is always BA-entered manually (e.g. "Khách hàng", "Nội bộ team", "Team Marketing") with no default or inference. Questions still **Open** leave all three columns blank (`—`). Checklist gained a matching item to catch missing values on **Confirmed** rows.
+
+### Fixed
+
+- **`ak task next` treated `ingest-data` as a 2-gate flow** — a stale assumption left over from before Gate 3 (task creation & ticket generation) was added to `ingest-data` earlier in the same release cycle. `scripts/task.js` grouped it with `gen-doc`/`create-system-requirement` (`maxGate = 2`), so pausing via `ak task next` on Gate 2 would prematurely mark the task `status: 'done'` and `gateLabel(3, 'ingest-data')` returned `'Done'` instead of `'Sinh Task & Tạo Ticket'`. Split into its own 3-gate branch (`maxGate = 3`); `gen-doc`/`create-system-requirement` are unaffected.
+
 ## [0.2.0] - 2026-08-04
 
 ### Added

package/docs/common/INDEX.md

@@ -29,6 +29,7 @@
 | `99.Memory/` Project Brain — full design, scoring model, mem-id scheme, role/PM permissions | [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md) | v1.1 — Phase 1 (`draft/list/submit/remove`) is what's implemented today; later phases in this doc are roadmap, not shipped yet |
 | How updates to `AK-Docs`/`Shared-Docs` get reviewed — branch/Merge Request flow, who can merge to `main` | [Docs-Management-Flow.md](./Docs-Management-Flow.md) | Doc's own header says `Trạng thái: Draft — chờ PM review` — flag that when answering, don't present it as final policy |
 | PM/BrSE/Comtor — ingest a Backlog/Jira/SharePoint link or pasted text into `AK-Docs/01.QnA/` | [Project-Structure.md](./Project-Structure.md) (§ `01.QnA/`), `.claude/skills/ingest-data/SKILL.md` | `ak use` → taskType `ingest-data`, 2-gate flow (fetch/classify/draft → branch+MR). SharePoint link fetch is **not connected yet** — falls back to pasted text |
+| Any role — how to read `System-Requirement_v{N}.md` (who reads which field, Classification/Implementation Reference/Tech Reference meaning), why it's separate from UC Spec, and how to review/approve it without reading code | [System-Requirement-Read-Guide.md](./System-Requirement-Read-Guide.md) | Field glossary + Classification state machine (Gap/Assumption/Decision/Deviation) + FAQ (why not merge with UC Spec, who writes it, when to update) + 6-step review checklist |
 
 ## Unanswered topics (do not invent — say so and stop here)
 

package/docs/common/QUICK_START.md

@@ -382,7 +382,7 @@ ak execute ./testcases/AD10.md        # AI starts execute-flow with this TC file
 ak execute                            # AI asks: "TC file ở đâu?"
 ```
 
-Output lands in `ak-test/{repo}/results/{screenId}/run-{N}/` — never deleted between runs.
+Evidence (screenshots/video/trace.zip) lands in `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/` — never deleted between runs. Scripts, result/report/bug docs live in `AK-Docs/03.Testing/` instead (05.Scripts / 02.Reports / 06.Bugs) so they're versioned with the rest of the project's docs, while binary evidence stays out of that git history.
 
 ### Figma Design → Code
 

package/docs/common/System-Requirement-Read-Guide.md

@@ -0,0 +1,178 @@
+# Hướng Dẫn Đọc System Requirement (mọi role)
+
+> **Dành cho:** bất kỳ ai cần đọc một `System-Requirement_v{N}.md` — PM, Comtor, BrSE, Tester, Dev, Tech Lead. Mục tiêu của tài liệu này: giúp bạn biết **mình cần đọc phần nào**, đọc xong hiểu đúng, không cần đọc code hay đọc hết mọi dòng.
+> **Tài liệu được đọc:** `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md`, sinh ra bởi task type **"📐 Create System Requirement"** — cầu nối giữa UC Spec (BA) và code (Dev).
+> **Nếu bạn là người duyệt (approve)** tài liệu này, xem thêm Mục 5 (Checklist) — phần còn lại của guide vẫn áp dụng, checklist chỉ là bước cuối.
+
+---
+
+## 1. Ai đọc phần nào
+
+Mỗi `System-Requirement_v{N}.md` đã có sẵn bảng này ngay ở đầu file (nói 1 lần, không lặp lại theo từng dòng). Nhắc lại ở đây để bạn không cần mở file mới nhớ ra:
+
+| Field trong tài liệu | Ai cần đọc |
+|---|---|
+| `Requirement` | PM/BrSE/Comtor, Tester |
+| `System Behavior` | Tester |
+| `Error Response` | Tester (đầy đủ, gồm HTTP code) — PM/BrSE/Comtor chỉ cần câu thông báo hiển thị |
+| `Traced UC Ref` / `Traced UC BR` / `Traced Exception Flow` | PM/BrSE/Comtor (đối chiếu UC Spec) |
+| `Classification` | PM/BrSE/Comtor — dấu hiệu "cần quyết định" hoặc "đã chốt" |
+| `Implementation Reference` / `Tech Reference` | Dev |
+| Mục 5 (Acceptance Test Scenarios) | Tester |
+
+**Dev và AI đọc toàn bộ tài liệu.** Nếu bạn là PM/Comtor/BrSE và thấy 1 dòng `Implementation Reference` mình không hiểu — đó là bình thường, **bỏ qua**, không phải bạn thiếu kiến thức.
+
+---
+
+## 2. Cách đọc 1 item (Requirement/System Behavior/Implementation Reference)
+
+`System-Requirement_v{N}.md` được thiết kế theo 3 tầng, mỗi tầng cho 1 nhóm người đọc khác nhau trong **cùng một item**:
+
+| Tầng | Viết bằng | Dành cho | Bạn cần đọc? |
+|---|---|---|---|
+| **Requirement** | Ngôn ngữ nghiệp vụ, không có tên class/method/framework | PM, Comtor, BrSE, **Tester** | ✅ Luôn đọc |
+| **System Behavior** | Vẫn ngôn ngữ thường, mô tả điều kiện/thứ tự xử lý | BA, Tester | ✅ Luôn đọc |
+| **Error Response** | HTTP code + message hiển thị cho end-user | Tester | ✅ Đọc nếu là Validation/Exception |
+| **Implementation Reference / Tech Reference** | file:line, class, method, enum | Dev | ❌ **Bỏ qua được** — không phải Dev thì không cần đọc |
+
+**Nguyên tắc:** nếu bạn phải đọc `Implementation Reference` để hiểu `Requirement` đang nói gì, đó là **lỗi của tài liệu** (leak kỹ thuật lên tầng nghiệp vụ) — báo lại cho Dev viết lại, không phải bạn thiếu kiến thức.
+
+---
+
+## 3. Giải thích về Classification
+
+Mỗi item (FR/NFR/VR/ER) có thể mang 1 trong 4 nhãn `Classification`.
+
+| Nhãn | Nghĩa | Ai tạo ra | Hành động bạn cần làm |
+|---|---|---|---|
+| **Gap** | UC Spec chưa có nội dung này | Dev, khi viết tài liệu | PM/BA phải trả lời. **Còn Gap chưa trả lời → tài liệu chưa được approve.** |
+| **Assumption** | Dev suy đoán, chưa ai xác nhận | Dev | PM confirm → thành Decision. PM reject → quay lại Gap |
+| **Decision** | Đã chốt, có ngày và người chốt | Sau khi PM trả lời | Chỉ đọc, không cần hành động |
+| **Deviation** | Code hiện tại khác UC Spec | Dev, khi so sánh với code thật | BA/PM chọn: sửa code theo UC Spec, hoặc sửa UC Spec theo code |
+
+### Khi 1 item có nhiều quyết định — cách đọc
+
+Trường hợp 1 item có **2+ quyết định** liên quan (ví dụ BA chốt 1 phần, Dev chốt phần còn lại). Ví dụ:
+
+```
+Classification: Gap → Decision
+  - OQ-35 (BA): sử dụng mã lượt đặt hàng để xác định yêu cầu đặt hàng trùng và tránh tạo đơn nhiều lần.
+  - D-03 (Dev): nếu mã lượt đặt hàng đã được xử lý, không tạo đơn mới; trả về HTTP 400 kèm đơn đã tạo trước đó. Mã có hiệu lực trong 30 phút.
+```
+
+Cách đọc: mỗi dòng là **1 mã số + ai chốt + nội dung ngắn**.
+- `OQ-xx` = quyết định gốc do BA chốt, kế thừa từ UC Spec (thường trong lúc Q&A trước khi UC Spec được ký duyệt).
+- `D-xx` = quyết định phát sinh riêng khi Dev soạn tài liệu System Requirement này (ví dụ: UC Spec chốt "phải chống trùng đơn" nhưng chưa viết rõ máy chủ trả gì — Dev phải tự chốt thêm chi tiết kỹ thuật đó, ghi lại thành D-xx để không tự quyết ngầm).
+
+Nếu bạn không nhớ hoặc không đồng ý với 1 trong các quyết định đó, nêu lại ngay — đừng chờ tới khi ra sản phẩm.
+
+---
+
+## 4. Workflow trạng thái Classification
+
+```mermaid
+%%{init: {'flowchart': {'curve': 'linear'}}}%%
+flowchart TD
+    Start([Dev viết draft]) --> Gap[Gap]
+    Gap -->|"PM/BA trả lời chắc chắn"| Decision[Decision]
+    Gap -->|"PM/BA trả lời<br/>nhưng chưa chắc 100%"| Assumption[Assumption]
+    Assumption -->|"PM confirm đúng"| Decision
+    Assumption -->|"PM reject / cần hỏi lại"| Gap
+    Decision -->|"sau này Dev thấy<br/>code thực tế khác"| Deviation[Deviation]
+    Deviation -->|"PM chọn sửa code<br/>theo UC Spec (đã fix xong)"| Decision
+    Deviation -->|"PM chọn giữ code, sửa UC Spec<br/>(BA cập nhật UC Spec, tăng version mới)"| Decision
+```
+
+**Rule:** tài liệu **không được approve** khi còn item ở trạng thái `Gap` chưa trả lời. `Assumption` được phép tồn tại tạm nếu PM đã xác nhận "tạm chấp nhận, sẽ chốt sau" — nhưng phải ghi rõ trong Mục 8 (Decision Log), không được im lặng bỏ qua.
+
+---
+
+## 5. Checklist Review (dành cho người duyệt — không cần đọc code)
+
+Làm theo đúng thứ tự — dừng và reject ngay khi 1 bước fail.
+
+### Bước 1 — Đọc Executive Summary (30 giây)
+- [ ] `Traceability coverage` = X/X? Thiếu → tài liệu chưa đầy đủ, trả lại Dev.
+- [ ] `Action needed from PM` có danh sách → đây là Gap/Assumption bạn phải trả lời **trước**, ngay tại bước này.
+
+### Bước 2 — Khớp 1-1 với UC Spec (Mục 0 — Traceability Matrix)
+- [ ] Mở UC Spec `v{N}` ghi ở header song song.
+- [ ] Mỗi Main/Alternative/Exception Flow, mỗi Business Rule trong UC Spec → tìm đúng 1 dòng tương ứng trong Traceability Matrix.
+- [ ] Thiếu dòng nào → **reject**.
+
+### Bước 3 — Đọc tầng Requirement (Mục 1–4)
+- [ ] Chỉ đọc `Requirement` + `System Behavior` — bỏ qua `Implementation Reference`.
+- [ ] Thấy tên class/method/framework lọt vào `Requirement`/`System Behavior` → **reject**, yêu cầu viết lại.
+- [ ] Với Validation/Exception: `Error Response` phải giữ HTTP code + message hiển thị.
+
+### Bước 4 — Xử lý từng nhãn Classification
+- [ ] `Gap`/`Assumption` → trả lời theo workflow ở Mục 4.
+- [ ] `Deviation` → chọn rõ: sửa code hay sửa UC Spec — không để lơ lửng.
+- [ ] `Decision` → chỉ xác nhận đúng là điều đã chốt; không nhớ đã chốt → hỏi lại, đừng mặc định đúng.
+
+### Bước 5 — Đối chiếu Mục 7 (Assumptions/Gaps/Decisions/Deviations)
+- [ ] Mọi item có nhãn ở Mục 1–4 phải có dòng tương ứng ở Mục 7. Thiếu → reject.
+
+### Bước 6 — Quyết định
+- [ ] Còn `Gap` chưa trả lời → **không approve**.
+- [ ] Pass hết Bước 1–5 → gõ `APPROVED`.
+
+---
+
+## 6. Câu hỏi thường gặp (FAQ)
+
+### System Requirement để làm gì? Tôi có UC Spec rồi thì cần gì System Requirement nữa?
+
+UC Spec và System Requirement trả lời 2 câu hỏi khác nhau:
+
+- **UC Spec (BA viết)** trả lời: *"hệ thống PHẢI làm gì theo mong muốn của khách/nghiệp vụ?"* — viết **trước khi** biết chắc code hiện tại đang làm gì, không cần Dev tham gia để ký duyệt.
+- **System Requirement (Dev viết, sau khi đọc UC Spec + mở code thật ra đối chiếu)** trả lời: *"code hiện tại đã làm đúng chưa? Còn thiếu gì? Có tình huống nào UC Spec không viết tới nhưng hệ thống vẫn phải xử lý?"*
+
+Ví dụ thật trong tài liệu BUY074: UC Spec chỉ viết "chống bán vượt tồn kho", nhưng KHÔNG viết tới tình huống "2 khách đặt cùng 1 sản phẩm cùng lúc thì ai thắng, ai thua, giỏ của người thua xử lý sao, có bị deadlock không nếu đơn có nhiều sản phẩm giao nhau". Đây là những **Gap** mà chỉ khi Dev đọc code + tưởng tượng ra kịch bản thật mới phát hiện được — BA khi viết UC Spec không có đủ góc nhìn kỹ thuật để lường trước. System Requirement chính là nơi những Gap này được phát hiện, hỏi lại BA/PM, và ghi lại chốt là gì.
+
+Nói ngắn: **UC Spec = ý định. System Requirement = ý định đó khi va vào code thật thì phải cụ thể hoá ra sao.**
+
+### Vì sao không gộp UC Spec và System Requirement thành 1 tài liệu, review 1 lần cho gọn?
+
+3 lý do:
+
+1. **Thời điểm ký duyệt khác nhau.** UC Spec phải được BA/PM ký duyệt **trước**, không cần chờ Dev có thời gian đọc hết code. Nếu gộp 2 tài liệu, UC Spec sẽ bị kẹt chờ Dev investigate code xong mới ký được — làm chậm cả quy trình dù bản chất nghiệp vụ đã rõ và có thể duyệt độc lập với chi tiết kỹ thuật.
+2. **Người review và tiêu chí review khác nhau.** Review UC Spec cần Dev đánh giá "khả thi kỹ thuật ở mức khái niệm" + Tester đánh giá "khả năng test được ở mức khái niệm". Review System Requirement cần Dev + Tester **đối chiếu từng dòng với UC Spec** (khác câu hỏi, khác độ chi tiết) — trộn 2 việc vào 1 lần review dễ khiến người review làm qua loa 1 trong 2, thay vì làm kỹ cả 2.
+3. **Traceability rõ ràng hơn khi tách riêng.** Mỗi `System-Requirement_v{N}` phải matching đúng 1 phiên bản UC Spec (`UC-Spec-Version` header) — nếu 2 tài liệu là một, việc UC Spec đổi version (do yêu cầu nghiệp vụ đổi) và System Requirement đổi version (do Dev phát hiện thêm case khi code) sẽ lẫn vào nhau, khó biết cái gì đổi vì lý do gì.
+
+**Nhưng:** Dự án có thể linh hoạt sắp xếp gộp 1 buổi review chung cho 2 tài liệu này, trong trường hợp có thể output 2 tài liệu cùng nhau thay vì phải chờ 1 khoảng thời gian dài để Dev điều tra.
+
+### System Requirement có được phép thay đổi/thêm nội dung so với UC Spec không?
+
+Không. System Requirement **không bao giờ bịa ra** nội dung mà UC Spec không có — mọi FR/VR/ER phải trace được về 1 dòng cụ thể trong UC Spec, hoặc được đánh dấu `Gap`/`Assumption`/`Deviation` và chờ PM/BA xác nhận. Nếu bạn thấy 1 `Requirement` mà không tìm được nguồn trong UC Spec, đó là lỗi — báo lại ngay (xem Bước 2/3 ở Mục 5).
+
+### Khi nào cần viết lại/update System Requirement?
+
+Hai trường hợp: (1) UC Spec lên version mới (BA sửa yêu cầu) → System Requirement phải `RESYNC` theo version mới; (2) trong lúc code 1 ticket, Dev phát hiện 1 case UC Spec có viết nhưng System Requirement bỏ sót → được đề xuất bổ sung, ghi thêm 1 dòng ở Change Log (Mục 9), không cần tăng version vì UC Spec chưa đổi.
+
+### Mục 8 (Decision Log) chỉ có 1 dòng ngắn — thiếu thông tin à?
+
+Không thiếu — chủ ý tránh viết trùng 2 nơi. Chi tiết đầy đủ đã nằm trong dòng `Classification` của item tương ứng ở Mục 1–4; Mục 8 chỉ là bảng tra cứu ngược (ID → ai chốt → ngày → 1 dòng tóm tắt).
+
+### Tôi không hiểu `Implementation Reference` ghi gì, có sao không?
+
+Tuỳ role. Nếu bạn là **PM/BrSE/Comtor/Tester** — không sao, tầng đó không dành cho bạn (xem Mục 1, 2); nếu bạn *cần* hiểu nó để đánh giá đúng/sai của `Requirement`, đó là lỗi tài liệu — báo lại, đừng tự trách mình thiếu kiến thức.
+
+Nếu bạn là **Dev** — **bắt buộc phải hiểu**, vì đây chính là field ghi cho bạn (file:line/class/method để code) và AI cũng dựa vào nó ở Gate 3 coding. Không hiểu được thì không phải lỗi của bạn cần bỏ qua, mà là dấu hiệu tài liệu viết thiếu rõ (ví dụ thiếu context, path sai, hoặc tham chiếu tới code không còn tồn tại) — cần hỏi lại người viết (Dev khác/AI) hoặc tự mở code kiểm tra trước khi bắt đầu implement, không được đoán.
+
+### `Tech Reference` trong Mục 6.2 (Glossary) khác gì `Implementation Reference`?
+
+`Implementation Reference` nằm rải trong từng item, chỉ Dev cần. `Tech Reference` ở Mục 6.2 là **bảng tra cứu tập trung** — mỗi giá trị kỹ thuật (ví dụ enum `TagStatusEnum::PENDING`) map sang 1 ý nghĩa nghiệp vụ đã được PM xác nhận (`Decision`) hoặc chưa (`Assumption`). Dùng bảng này khi muốn biết "giá trị thô này nghĩa là gì với nghiệp vụ" mà không cần lục từng item.
+
+### Tài liệu này có thay UC Spec không?
+
+Không. UC Spec là nguồn nghiệp vụ gốc (BA sign-off). System Requirement là bản dịch sang góc nhìn Dev + trace lại UC Spec.
+
+---
+
+## 7. Liên quan
+
+- Skill sinh ra tài liệu này: `.claude/skills/create-system-requirement/SKILL.md`
+- Template: `.claude/skills/create-system-requirement/system-requirement-template-v1.md`
+- Cấu trúc thư mục `02.BA-Specs/`: [BA-Specs-Structure.md](./BA-Specs-Structure.md)
+- Quy trình SDLC end-to-end (Checkpoint #2/#3, gộp thread review): `docs/internal/SDLC-Unified-Workflow_v1.0.md`

package/docs/common/Testing-Structure.md

@@ -38,30 +38,34 @@
 │       ├── Users.csv
 │       └── Fixtures.sql
 │
-├── 04.Evidence/                            # Gate 3: Screenshots, videos, logs per execution
-│   └── F-001_User-Login/
-│       ├── TICKET-100_2026-06-15/          # Ticket + date to identify execution round
-│       │   ├── TC_001_PASS/
-│       │   │   └── Screenshot.png
-│       │   └── TC_002_FAIL/
-│       │       ├── Screenshot.png
-│       │       └── Video.mp4
-│       └── TICKET-100_Retest_2026-06-18/
-│           └── TC_002_PASS/
-│               └── Screenshot.png
+├── 04.Evidence/                            # ⚠️ MUST be in .gitignore — binary (screenshots/video/trace.zip)
+│   ├── F-001_User-Login/                   # manual QA evidence (screenshots attached by hand)
+│   │   └── TICKET-100_2026-06-15/          # Ticket + date to identify execution round
+│   │       └── TC_003_PASS/
+│   │           └── Screenshot.png
+│   └── {repo}/{featureDir}/run-{N}/        # execute-test flow's AUTOMATION evidence (Gate 3)
+│       ├── results.json                    # Playwright JSON output
+│       └── {TC_ID}-{scenario}/
+│           ├── step-NN-{desc}.png
+│           └── trace.zip
 │
-├── 05.Scripts/                             # Playwright automation (by Repo → Feature)
+├── 05.Scripts/                             # Playwright automation — RUNNABLE project (by Repo → Feature)
+│   ├── package.json                        # 1 install for the whole 05.Scripts tree
+│   ├── tsconfig.json
+│   ├── node_modules/                       # gitignored — see Rules
+│   ├── Shared/                             # Fixtures, helpers, evidence-helper used across repos
+│   │   ├── fixtures/test.ts
+│   │   ├── BasePage.ts
+│   │   └── evidence-helper.ts              # waitForUiSettled / highlightElement / captureStepEvidence
 │   ├── Repo1/                              # e.g. frontend app
-│   │   ├── playwright.config.ts            # baseURL, browser config for this repo
+│   │   ├── playwright.config.ts            # baseURL, EVIDENCE_DIR-driven outputDir for this repo
+│   │   ├── pages/LoginPage.ts
 │   │   └── F-001_User-Login/
 │   │       └── Login.spec.ts
-│   ├── Repo2/                              # e.g. admin app
-│   │   ├── playwright.config.ts
-│   │   └── F-003_Admin-Panel/
-│   │       └── Admin.spec.ts
-│   └── Shared/                             # Fixtures, helpers used across repos
-│       ├── Fixtures.ts
-│       └── Helpers.ts
+│   └── Repo2/                              # e.g. admin app
+│       ├── playwright.config.ts
+│       └── F-003_Admin-Panel/
+│           └── Admin.spec.ts
 │
 ├── 06.Bugs/                                # Gate 3: Bug reports (AI draft on TC fail)
 │   └── F-001_User-Login/
@@ -109,9 +113,9 @@
 | Gate | Output | Folder |
 |---|---|---|
 | Gate 1 | Chuẩn bị & Lập kế hoạch thực thi | (Console output / Work Plan) |
-| Gate 2 | Đồng bộ kịch bản kiểm thử (Script Sync) | `05.Scripts/[Repo]/[Feature]/[Feature].spec.ts` |
-| Gate 3 | Thực thi test & Thu thập evidence | `04.Evidence/[Feature]/[Ticket]_[Date]/` & `06.Bugs/[Feature]/` |
-| Gate 4 | Báo cáo test & Log bug | `02.Reports/[Feature]/[Ticket]/Execution-Report.md` |
+| Gate 2 | Đồng bộ kịch bản kiểm thử (Script Sync) | `05.Scripts/[Repo]/[Feature]/[Feature].spec.ts` (project chạy được tại chỗ — có `package.json`/`node_modules`) |
+| Gate 3 | Thực thi test & Thu thập evidence | Binary evidence (screenshot/video/`trace.zip`) → `04.Evidence/[Repo]/[Feature]/run-{N}/` (gitignored, xem Rules) & bug reports (text) → `06.Bugs/[Repo]/[Feature]/run-{N}/` |
+| Gate 4 | Báo cáo test & Log bug | `02.Reports/[Repo]/[Feature]/run-{N}/testreport.md` |
 
 ---
 
@@ -119,6 +123,8 @@
 
 - Không tự sửa template — template nằm trong shared repo riêng
 - Lưu testcase và kết quả lên GitLab **sau khi Gate 4 được APPROVED**
-- Khi retest: tạo subfolder `TICKET-XXX_Retest_Date/` mới trong Evidence — không ghi đè cũ
-- `05.Scripts/` chỉ chứa `.spec.ts` và `playwright.config.ts` — không chứa testcase `.md`
+- Khi retest: tạo subfolder `run-{N+1}/` mới trong Evidence & Reports — không ghi đè cũ
+- `05.Scripts/` là 1 Playwright project chạy tại chỗ trong AK-Docs (`.spec.ts`, `playwright.config.ts`, `pages/`, `Shared/` fixtures + `evidence-helper.ts`, `package.json`, `node_modules/`) — không chứa testcase `.md`
+- `05.Scripts/**/node_modules/`, `test-results/`, `playwright-report/`, `blob-report/` **phải** nằm trong `.gitignore` của repo chứa AK-Docs — execute-flow Gate 1 tự kiểm tra và thêm nếu thiếu
+- **`04.Evidence/` phải nằm trong `.gitignore`** — dù chứa cả evidence tay (manual QA) và evidence automation (execute-test), toàn bộ nội dung là binary (screenshot/video/`trace.zip`), không commit lên Git. Không có `ak-test/` hay working dir nào khác ngoài AK-Docs cho flow này nữa.
 - `07.AI-Artifacts/` là working docs của AI — không phải tài liệu chính thức

package/docs/common/cli-reference.md

@@ -171,19 +171,21 @@ ak execute                                   # manual — AI asks for TC file
 - `[target]` — Optional. A ticket ID (`PROJ-44`), a path to a TC file (`./testcases/AD10.md`), or omitted for manual entry.
 
 **What it does (4 gates):**
-1. **Gate 1 — Pre-flight:** Parse TC file, verify `ak-test/{repo}/` and `playwright.config.ts` exist, check `BASE_URL`
-2. **Gate 2 — Script Sync:** Hash-based sync — gen new TCs, update changed, skip unchanged. Uses Playwright MCP for real selectors (never fabricates).
-3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence into `run-{N}/`, update TC file R1/R2 columns (`✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`)
-4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, confirm each bug with TESTER before logging to Jira
+1. **Gate 1 — Pre-flight:** Parse TC file, verify `AK-Docs/03.Testing/` subfolders and `AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts` exist (auto-scaffold if missing), check `BASE_URL`
+2. **Gate 2 — Script Sync:** Hash-based sync — gen new TCs, update changed, skip unchanged. Uses Playwright MCP for real selectors (never fabricates). Every step captures evidence via `evidence-helper.ts` and asserts on actual Expected Result content (see "DOM Verification Rules" in `execute-flow` SKILL.md).
+3. **Gate 3 — Execute & Evidence:** Run Playwright from `AK-Docs/03.Testing/05.Scripts/`, evidence written into `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/` via `EVIDENCE_DIR`, update TC file R1/R2 columns (`✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`)
+4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md` in AK-Docs, confirm each bug with TESTER before logging to Jira
 
 **Output structure:**
 ```
-ak-test/{repo}/
-├── scripts/{screenId}/{ScreenID}.spec.ts
-└── results/{screenId}/run-{N}/
-    ├── {TC_ID}-{scenario}/  (screenshots, trace.zip, result.md)
-    ├── bugs/BUG-NNN-{slug}.md
-    └── testreport.md
+AK-Docs/03.Testing/
+├── 04.Evidence/{repo}/{featureDir}/run-{N}/            # gitignored — screenshots, trace.zip
+│   └── {TC_ID}-{scenario}/
+├── 05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts   # runnable Playwright project
+├── 02.Reports/{repo}/{featureDir}/run-{N}/
+│   ├── {TC_ID}-{scenario}/result.md
+│   └── testreport.md
+└── 06.Bugs/{repo}/{featureDir}/run-{N}/BUG-NNN-{slug}.md
 ```
 
 **Example:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.2.0",
+  "version": "0.2.2-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {