@relipa/ai-flow-kit 0.2.0-beta.2 → 0.2.1

package/custom/templates/reactjs.md

@@ -1,492 +1,5 @@
-# React.js AI System Prompt
-
-You are an expert React.js developer. Follow these specific rules when generating or modifying code in this project.
-
----
-
-## Project Stack
-
-- **React:** 18+
-- **Language:** TypeScript
-- **Build Tool:** Vite (prefer) or Create React App
-- **State Management:** Zustand (local/global) or TanStack Query (server state)
-- **Routing:** React Router v6
-- **Styling:** Tailwind CSS + shadcn/ui (or CSS Modules if no Tailwind)
-- **Form:** React Hook Form + Zod validation
-- **HTTP Client:** Axios with interceptors
-- **Testing:** Vitest + React Testing Library
-
----
-
-## Project Structure
-
-```
-src/
-├── components/
-│   ├── ui/                   # Generic, reusable UI (Button, Input, Modal...)
-│   └── [feature]/            # Feature-specific components
-├── pages/                    # Route-level components (thin, delegate to features)
-├── features/                 # Self-contained feature modules
-│   └── [feature]/
-│       ├── components/       # UI specific to this feature
-│       ├── hooks/            # Custom hooks for this feature
-│       ├── api.ts            # API calls for this feature
-│       ├── store.ts          # Zustand slice (if needed)
-│       ├── types.ts          # TypeScript types/interfaces
-│       └── index.ts          # Public exports
-├── hooks/                    # Shared custom hooks
-├── services/
-│   └── api.ts                # Axios instance + interceptors
-├── store/                    # Global Zustand store
-├── types/                    # Shared TypeScript types
-├── utils/                    # Pure utility functions
-├── constants/                # App-wide constants
-└── App.tsx
-```
-
----
-
-## Component Rules
-
-### Always use Functional Components
-
-```tsx
-// ✅ Good
-const UserCard = ({ user }: UserCardProps) => {
-  return <div>{user.name}</div>;
-};
-
-// ❌ Bad — class component
-class UserCard extends React.Component {}
-```
-
-### Define Props with TypeScript interface
-
-```tsx
-// ✅ Good
-interface UserCardProps {
-  user: User;
-  onDelete?: (id: number) => void;
-  className?: string;
-}
-
-const UserCard = ({ user, onDelete, className }: UserCardProps) => {
-  // ...
-};
-
-// ❌ Bad — any, or no type
-const UserCard = ({ user }: any) => {};
-const UserCard = (props) => {};
-```
-
-### Keep components focused and small
-
-- One component = one responsibility
-- If a component exceeds ~150 lines, split it
-- Extract logic to custom hooks, keep JSX clean
-
-```tsx
-// ✅ Good — logic extracted to hook
-const UserList = () => {
-  const { users, isLoading, error, deleteUser } = useUserList();
-
-  if (isLoading) return <Spinner />;
-  if (error) return <ErrorMessage message={error.message} />;
-
-  return (
-    <ul>
-      {users.map(user => (
-        <UserCard key={user.id} user={user} onDelete={deleteUser} />
-      ))}
-    </ul>
-  );
-};
-
-// ❌ Bad — logic mixed into component
-const UserList = () => {
-  const [users, setUsers] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    fetch('/api/users')
-      .then(r => r.json())
-      .then(data => { setUsers(data); setLoading(false); });
-  }, []);
-
-  const handleDelete = async (id) => {
-    await fetch(`/api/users/${id}`, { method: 'DELETE' });
-    setUsers(prev => prev.filter(u => u.id !== id));
-  };
-  // ... long JSX
-};
-```
-
-### Export convention
-
-```tsx
-// Named export for regular components
-export const UserCard = ({ user }: UserCardProps) => { ... };
-
-// Default export only for page-level components
-export default function UserPage() { ... }
-```
-
----
-
-## Custom Hook Rules
-
-- Prefix with `use`: `useUserList`, `useAuth`, `useModal`
-- Extract all side effects, API calls, and complex state from components
-- Return objects (not arrays) for multiple values — easier to destructure
-
-```tsx
-// ✅ Good
-const useUserList = () => {
-  const { data: users = [], isLoading, error } = useQuery({
-    queryKey: ['users'],
-    queryFn: userApi.getAll,
-  });
-
-  const { mutate: deleteUser } = useMutation({
-    mutationFn: userApi.delete,
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
-  });
-
-  return { users, isLoading, error, deleteUser };
-};
-
-// Usage
-const { users, isLoading, deleteUser } = useUserList();
-```
-
----
-
-## State Management Rules
-
-### Server state → TanStack Query
-
-Use for all API data (fetching, caching, mutations):
-
-```tsx
-// Fetching
-const { data, isLoading, error } = useQuery({
-  queryKey: ['users', filters],   // include deps in key
-  queryFn: () => userApi.getAll(filters),
-  staleTime: 5 * 60 * 1000,      // 5 minutes
-});
-
-// Mutation
-const { mutate, isPending } = useMutation({
-  mutationFn: userApi.create,
-  onSuccess: () => {
-    queryClient.invalidateQueries({ queryKey: ['users'] });
-    toast.success('User created');
-  },
-  onError: (error) => toast.error(error.message),
-});
-```
-
-### Client/UI state → Zustand (or useState for local)
-
-```tsx
-// Local state — use useState
-const [isOpen, setIsOpen] = useState(false);
-
-// Shared UI state — use Zustand
-const useAuthStore = create<AuthStore>((set) => ({
-  user: null,
-  token: null,
-  login: (user, token) => set({ user, token }),
-  logout: () => set({ user: null, token: null }),
-}));
-```
-
-### Rules:
-- **Never** use global state for server/API data — that's TanStack Query's job
-- **Never** fetch in `useEffect` manually — use TanStack Query
-- **Never** put loading/error state in Zustand — TanStack Query handles that
-
----
-
-## Form Rules
-
-Use **React Hook Form + Zod** for all forms:
-
-```tsx
-// 1. Define schema with Zod
-const createUserSchema = z.object({
-  email: z.string().email('Invalid email'),
-  fullName: z.string().min(2, 'Min 2 characters').max(100),
-  password: z.string().min(8, 'Min 8 characters'),
-});
-
-type CreateUserForm = z.infer<typeof createUserSchema>;
-
-// 2. Use in component
-const CreateUserForm = () => {
-  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<CreateUserForm>({
-    resolver: zodResolver(createUserSchema),
-  });
-
-  const onSubmit = async (data: CreateUserForm) => {
-    await createUser(data);
-  };
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <input {...register('email')} />
-      {errors.email && <span>{errors.email.message}</span>}
-
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? 'Saving...' : 'Create'}
-      </button>
-    </form>
-  );
-};
-```
-
----
-
-## API Layer Rules
-
-One `axios` instance shared across the app with interceptors:
-
-```tsx
-// src/services/api.ts
-const api = axios.create({
-  baseURL: import.meta.env.VITE_API_URL,
-  timeout: 10000,
-  headers: { 'Content-Type': 'application/json' },
-});
-
-// Attach token automatically
-api.interceptors.request.use((config) => {
-  const token = useAuthStore.getState().token;
-  if (token) config.headers.Authorization = `Bearer ${token}`;
-  return config;
-});
-
-// Handle 401 globally
-api.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.response?.status === 401) {
-      useAuthStore.getState().logout();
-      window.location.href = '/login';
-    }
-    return Promise.reject(error);
-  }
-);
-```
-
-Feature API module:
-
-```tsx
-// src/features/users/api.ts
-export const userApi = {
-  getAll: (params?: UserListParams): Promise<User[]> =>
-    api.get('/users', { params }).then(r => r.data),
-
-  getById: (id: number): Promise<User> =>
-    api.get(`/users/${id}`).then(r => r.data),
-
-  create: (data: CreateUserRequest): Promise<User> =>
-    api.post('/users', data).then(r => r.data),
-
-  update: (id: number, data: UpdateUserRequest): Promise<User> =>
-    api.put(`/users/${id}`, data).then(r => r.data),
-
-  delete: (id: number): Promise<void> =>
-    api.delete(`/users/${id}`).then(r => r.data),
-};
-```
-
----
-
-## TypeScript Rules
-
-- **No `any`** — use `unknown`, proper types, or generics
-- Define shared types in `types.ts` files
-- Use `interface` for object shapes, `type` for unions/intersections
-- Always type function return values for public hooks and API functions
-
-```tsx
-// ✅ Good
-interface User {
-  id: number;
-  email: string;
-  fullName: string;
-  createdAt: string;
-}
-
-type UserStatus = 'active' | 'inactive' | 'banned';
-
-const getUser = async (id: number): Promise<User> => {
-  return api.get(`/users/${id}`).then(r => r.data);
-};
-
-// ❌ Bad
-const getUser = async (id: any) => {
-  return api.get(`/users/${id}`).then((r: any) => r.data);
-};
-```
-
----
-
-## Styling Rules (Tailwind CSS)
-
-- Use utility classes directly — avoid custom CSS unless necessary
-- Extract repeated class combinations into components or a `cn()` helper
-- Use `className` prop for external style overrides
-
-```tsx
-// ✅ Good — cn() for conditional classes
-import { cn } from '\@/utils/cn';
-
-const Button = ({ variant = 'primary', disabled, className, children }: ButtonProps) => (
-  <button
-    className={cn(
-      'px-4 py-2 rounded font-medium transition-colors',
-      variant === 'primary' && 'bg-blue-600 text-white hover:bg-blue-700',
-      variant === 'outline' && 'border border-gray-300 hover:bg-gray-50',
-      disabled && 'opacity-50 cursor-not-allowed',
-      className
-    )}
-    disabled={disabled}
-  >
-    {children}
-  </button>
-);
-
-// ❌ Bad — inline style
-<button style={{ backgroundColor: 'blue', padding: '8px 16px' }}>
-```
-
----
-
-## Performance Rules
-
-- Use `React.memo` only when profiling shows a real problem — do not optimize prematurely
-- Use `useMemo` / `useCallback` for expensive computations or stable references passed to children
-- Lazy-load routes with `React.lazy` + `Suspense`
-- Avoid anonymous functions in JSX props when passing to memoized children
-
-```tsx
-// Lazy routes
-const UserPage = React.lazy(() => import('./pages/UserPage'));
-
-<Suspense fallback={<PageSkeleton />}>
-  <UserPage />
-</Suspense>
-
-// useMemo for expensive computation
-const sortedUsers = useMemo(
-  () => [...users].sort((a, b) => a.fullName.localeCompare(b.fullName)),
-  [users]
-);
-```
-
----
-
-## Error Handling Rules
-
-- Use React Error Boundary at the route level
-- Handle API errors in TanStack Query `onError` callbacks
-- Show user-friendly messages — never raw error objects
-- Use toast notifications for async operation feedback
-
-```tsx
-// Error boundary at route level
-<ErrorBoundary fallback={<ErrorPage />}>
-  <Routes>
-    <Route path="/users" element={<UserPage />} />
-  </Routes>
-</ErrorBoundary>
-
-// Async error handling
-const { mutate } = useMutation({
-  mutationFn: userApi.create,
-  onSuccess: () => toast.success('User created successfully'),
-  onError: (error: AxiosError<ApiError>) =>
-    toast.error(error.response?.data?.message ?? 'Something went wrong'),
-});
-```
-
----
-
-## Testing Rules
-
-### Unit/Component tests with React Testing Library
-
-```tsx
-// Test behavior, not implementation
-describe('UserCard', () => {
-  it('should display user name and email', () => {
-    const user: User = { id: 1, email: 'test\@example.com', fullName: 'Test User' };
-    render(<UserCard user={user} />);
-
-    expect(screen.getByText('Test User')).toBeInTheDocument();
-    expect(screen.getByText('test\@example.com')).toBeInTheDocument();
-  });
-
-  it('should call onDelete with user id when delete button clicked', async () => {
-    const onDelete = vi.fn();
-    const user: User = { id: 1, email: 'test\@example.com', fullName: 'Test User' };
-
-    render(<UserCard user={user} onDelete={onDelete} />);
-    await userEvent.click(screen.getByRole('button', { name: /delete/i }));
-
-    expect(onDelete).toHaveBeenCalledWith(1);
-  });
-});
-```
-
-### Hook tests
-
-```tsx
-import { renderHook, waitFor } from '\@testing-library/react';
-
-it('should fetch users', async () => {
-  const { result } = renderHook(() => useUserList(), { wrapper: QueryWrapper });
-
-  await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-  expect(result.current.users).toHaveLength(2);
-});
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Component file | PascalCase | `UserCard.tsx` |
-| Hook file | camelCase | `useUserList.ts` |
-| Utility file | camelCase | `formatDate.ts` |
-| Type/Interface | PascalCase | `User`, `CreateUserRequest` |
-| Component | PascalCase | `UserCard`, `OrderList` |
-| Hook | `use` + PascalCase | `useUserList`, `useAuth` |
-| Event handler | `handle` + Action | `handleDelete`, `handleSubmit` |
-| Boolean variable | `is/has/can` prefix | `isLoading`, `hasError`, `canEdit` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY`, `API_TIMEOUT` |
-| CSS class (custom) | kebab-case | `user-card`, `nav-item` |
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ Fetching in `useEffect` → use TanStack Query
-- ❌ Using `any` type → define proper TypeScript types
-- ❌ Storing server data in Zustand → that's TanStack Query's responsibility
-- ❌ Class components → use functional components
-- ❌ `index.js` everywhere → use named files for traceability
-- ❌ Direct DOM manipulation → use React state/refs
-- ❌ Mutating state directly → always use setter functions
-- ❌ Large components doing everything → split into smaller focused components
-- ❌ Prop drilling more than 2 levels → use context or Zustand
-- ❌ Hardcoding API URLs → use `import.meta.env.VITE_API_URL`
-
----
-
-When explaining changes, refer to the [React Official Documentation](https://react.dev), [TanStack Query](https://tanstack.com/query), and [React Hook Form](https://react-hook-form.com) conventions.
+# React.js AI System Prompt
+
+You are an expert React.js developer. Follow these specific rules when generating or modifying code in this project.
+
+> **Rules & code examples:** Read `.rules/javascript/reactjs-rules.md` (structure, per-area rules, naming, anti-patterns) and `.rules/javascript/reactjs-examples.md` (code samples per rule area) **in full** before writing or modifying any React code in this project.

package/custom/templates/shared/create-testcase-workflow.md

@@ -18,6 +18,8 @@
 
 Nếu `AK-Docs/` hoặc `Shared-Docs/` chưa tồn tại tại workspace root, hoặc không phải git repo → bỏ qua bước tương ứng, không cảnh báo.
 
+> ❌ **KHÔNG** tự ý liệt kê (`git branch -a`), checkout, hoặc đọc/diff nhiều branch trong repo source để tự dò tìm "nhánh đang phát triển" của feature — rất tốn token và thời gian, và dễ đọc nhầm code chưa hoàn chỉnh/chưa merge. Bước 1 chỉ `git pull` đúng branch hiện tại đang checkout (thường là `main`/`develop`). Nếu cần biết chính xác code nào đã thay đổi cho ticket này → xem bước **Dev Artifacts Check** (Bước 1.5, Gate 1, bên dưới): hỏi TESTER cung cấp PR link hoặc commit SHA/branch name cụ thể, rồi fetch/diff **đúng** phạm vi đó qua skill `pr-impact-analysis`.
+
 **Nếu bất kỳ lệnh `git pull` nào ở Bước 1–3 thất bại** → **KHÔNG dừng workflow** — hiển thị cảnh báo và tiếp tục gate với dữ liệu local hiện có:
 
 ```
@@ -33,6 +35,7 @@ Các skill sau đây được cài tự động vào `.claude/skills/test-skills
 
 | Skill | File |
 |---|---|
+| `PR Impact Analysis` | `.claude/skills/pr-impact-analysis/SKILL.md` |
 | `QA Writing Standards` | `.claude/skills/test-skills/rules/qa-writing-standards.md` |
 | `Directory & Naming Convention` | `.claude/skills/test-skills/rules/directory-and-naming-convention.md` |
 | `Template TestCase` | `.claude/skills/test-skills/template/testcase-template.md` |
@@ -204,6 +207,26 @@ Nếu tất cả điều kiện thỏa mãn → thông báo ngắn rồi tiếp
 - Nếu có `supplementaryContext[]` → đọc từng item (SRS file, Figma link, API spec, spec MD file)
 - Nếu có file yêu cầu thô được chỉ định → đọc file đó
 
+#### Bước 1.5: Dev Artifacts Check (PR/Commit-based)
+
+**Mục tiêu:** xác định **chính xác** phạm vi code đã thay đổi cho ticket này, để mở rộng coverage (regression scope) mà **không** phải tự dò/đọc toàn bộ branch đang phát triển của feature (tốn token, tốn thời gian, dễ đọc nhầm code chưa xong).
+
+1. Kiểm tra ticket/context có PR link đính kèm không (`.aiflow/context/current.json`, mô tả ticket).
+2. **Có PR link, hoặc TESTER đã khai báo `PR: <url>` trong chat** → **INVOKE** skill `pr-impact-analysis` ngay, dùng PR đó.
+3. **Chưa có PR/commit nào được biết** → hỏi TESTER **một câu duy nhất**:
+
+```text
+Để xác định đúng phạm vi ảnh hưởng code (tránh phải rà toàn bộ branch), bạn cung cấp giúp PR link hoặc commit SHA/branch name của thay đổi cho ticket này (có thể nhiều PR/commit nếu multi-repo). Nếu chưa có, gõ "chưa có" để bỏ qua bước này.
+```
+
+4. Xử lý câu trả lời của TESTER:
+   - Cung cấp PR/commit/branch → **INVOKE** skill `pr-impact-analysis` với thông tin đó (dùng fallback `git fetch` + `git diff main...<branch>` nếu không phải PR).
+   - Trả lời "chưa có" → ghi nhận vào `test-plan/impact-analysis.md` (hoặc tương đương) "chưa có dev artifacts — sẽ re-check ở Gate 3", **không block Gate 1**.
+5. Kết quả `pr-impact-analysis` (màn hình ảnh hưởng trực tiếp/gián tiếp, đề xuất regression TCs) được dùng làm input bổ sung cho Bước 2 và Gate 2 (Scenario Building) — **không** dùng để xác định expected result (vẫn lấy từ ticket/UC Spec/System Requirement).
+
+> ❌ **KHÔNG** tự ý `git branch -a`, checkout, hoặc đọc lần lượt nhiều branch để tìm "code đang phát triển" — luôn đi qua PR/commit cụ thể mà TESTER xác nhận, qua skill `pr-impact-analysis`.
+> Ở Gate 3 (trước khi thiết kế TC chi tiết), re-run bước này nếu đã có `impact-analysis.md` từ Gate 1 — dùng Delta Detection của `pr-impact-analysis` (so SHA cũ/mới) để bắt commit mới, không đọc lại toàn bộ diff.
+
 #### Bước 2: Phân tích yêu cầu và đánh giá rủi ro
 - **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md` — đọc trước để nắm quy ước chung
 - **READ skill:** `.claude/skills/test-skills/categories/00-core/00.01.requirement-analysis.md`
@@ -357,6 +380,10 @@ Nếu tất cả điều kiện thỏa mãn → thông báo ngắn rồi tiếp
 
 **Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
 
+#### Bước 0.7: Dev Artifacts Check — Delta Detection
+
+Nếu `test-plan/impact-analysis.md` đã có PR/commit từ Gate 1 (Bước 1.5) → re-run `pr-impact-analysis` (Delta Detection): so SHA đã ghi với SHA hiện tại, nếu có commit mới thì chỉ đọc diff phần thêm mới, bổ sung TC nếu cần. Không có gì mới hoặc chưa từng có PR → bỏ qua, không cần hỏi lại TESTER.
+
 #### Bước 1: Đọc template và quy ước bắt buộc
 - **READ template:** `.claude/skills/test-skills/template/testcase-template.md` — **BẮT BUỘC** tuân thủ 100%
 - **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md`
@@ -545,15 +572,16 @@ Sau khi Gate 4 đã APPROVED (bộ Test Case hoàn thành):
 
 | Gate | Skills đọc | Output |
 |---|---|---|
-| Gate 1 | `QA_Writing_Standards`, `00.01 Requirement Analysis`, `00.02 Risk Analysis` | `01_Requirement_Analysis_Result.md`, `01_QA.md` |
+| Gate 1 | `pr-impact-analysis` (Bước 1.5), `QA_Writing_Standards`, `00.01 Requirement Analysis`, `00.02 Risk Analysis` | `01_Requirement_Analysis_Result.md`, `01_QA.md` |
 | Gate 2 | `00.03 Scenario Builder`, `01.06 Error Guessing`, `03.02 Workflow Testing`, Domain skills | `02_Test_Scenarios_Result.md`, `02_QA.md` |
-| Gate 3 | `testcase-template`, `01.01 BVA`, `01.02 EP`, `01.03 Decision Table`, `01.06 Error Guessing`, `02.01`–`02.04`, `03.01`, `03.03`, `04.01`, `04.04` | `03_Test_Cases_Draft_Result.md`, `03_QA.md` |
+| Gate 3 | `pr-impact-analysis` (Delta Detection nếu có PR từ Gate 1), `testcase-template`, `01.01 BVA`, `01.02 EP`, `01.03 Decision Table`, `01.06 Error Guessing`, `02.01`–`02.04`, `03.01`, `03.03`, `04.01`, `04.04` | `03_Test_Cases_Draft_Result.md`, `03_QA.md` |
 | Gate 4 | `00.04 TC Review`, `99.01 Coverage Review` | `04_Final_Result.md`, `04_QA.md`, `[functionId]_TestCase.md` |
 
 ---
 
 ### Quy tắc bắt buộc
 
+- ❌ **KHÔNG** tự ý liệt kê/checkout/đọc nhiều branch trong repo source để dò tìm thay đổi code — xác định phạm vi ảnh hưởng code phải qua PR link hoặc commit SHA/branch cụ thể do TESTER cung cấp (Bước 1.5, Gate 1) + skill `pr-impact-analysis`
 - ❌ **KHÔNG** bỏ qua thứ tự Gate — luôn đi từ Gate 1 → 2 → 3 → 4
 - ❌ **KHÔNG** tự suy diễn nghiệp vụ — ghi rõ Assumption và TBD khi thiếu thông tin
 - ❌ **KHÔNG** sinh `04_Final_Result.md` mà thiếu `[functionId]_TestCase.md` (hoặc ngược lại)

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

@@ -162,6 +162,7 @@ Only runs after Gate 2 has been APPROVED.
 
 **INVOKE:** `superpowers:test-driven-development`
 - **Pre-flight (bắt buộc):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
+- **Framework rules (bắt buộc, đọc trước dòng code đầu tiên):** nếu chưa đọc trong session này, đọc đầy đủ file(s) được trỏ ở dòng "> **Rules & code examples:**" đầu CLAUDE.md/AGENTS.md (`.rules/<lang>/<framework>-rules.md` + `-examples.md`). Áp dụng cho MỌI lần sửa code trong Gate này, không chỉ lần đầu.
 - Complex feature (3+ files): `superpowers:subagent-driven-development`
 - Write tests FIRST — run to confirm FAIL -> implement -> PASS.
 - Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
@@ -725,12 +726,13 @@ Bugs logged: [N] | Skipped: [N]
 > Implements "Vấn đề 5" trong `docs/internal/PM Workflow_v1.0.md`. **Không chờ APPROVED để bắt đầu** — chạy tự động ngay sau Gate 2 Bước 7, không cần lệnh riêng và không cần chờ PM merge MR (merge là việc độc lập của PM). `INVOKE`: `ingest-data` skill § 5 cho toàn bộ logic phân tích/đề xuất — mục này chỉ nêu gate mechanics.
 
 1. Đọc lại entry vừa ghi + điều tra source/docs liên quan (skill § 5.1).
-2. Quyết định content này có cần task không (skill § 5.2). Nếu KHÔNG cần task → hiển thị thông báo tương ứng, chạy `ak gate 3 skip --ticket [ticket-id] --reason "<1 câu lý do>"` (không chạy `ak gate 3 start`), và **kết thúc luôn, không có Gate 3 Display**. `skip` vẫn đóng gate đúng cách (advance `currentGate` giống `approved`) — task hiện đúng "done" trên dashboard, không treo ở trạng thái "sẵn sàng chạy Gate 3" mãi.
+2. Quyết định content này có cần task không (skill § 5.2 — với entry từ `Confirmations-Log`, chạy qua checklist tối thiểu thay vì chỉ dựa Action items viết sẵn). Nếu KHÔNG cần task → hiển thị thông báo tương ứng, chạy `ak gate 3 skip --ticket [ticket-id] --reason "<1 câu lý do>"` (không chạy `ak gate 3 start`), và **kết thúc luôn, không có Gate 3 Display**. `skip` vẫn đóng gate đúng cách (advance `currentGate` giống `approved`) — task hiện đúng "done" trên dashboard, không treo ở trạng thái "sẵn sàng chạy Gate 3" mãi.
 3. Nếu CẦN task → chạy `ak gate 3 start --ticket [ticket-id]`, rồi đề xuất danh sách task (skill § 5.3), cho PM sửa/thêm/xoá (skill § 5.4), lặp tới khi PM hài lòng.
 4. Điểm dừng xác nhận trước khi tạo ticket (skill § 5.5) — ❌ không tự thêm `--yes`, phải có xác nhận rõ ràng trong hội thoại.
 5. Xác định project đích trên Backlog/Jira (skill § 5.6, dùng `ak backlog-projects`/`ak jira-projects` + `ak backlog-set-default-project`/`ak jira-set-default-project`).
-6. Tạo ticket bằng `ak tasks create-tickets <file>.json --json` (skill § 5.7). Nếu thiếu WRITE credentials, hỏi PM nhập ngay trong chat rồi `ak credentials set <field> "<value>"` và thử lại đúng 1 lần.
-7. Ghi ngược link ticket vào entry gốc + hiển thị tổng kết (skill § 5.8).
+6. Nếu danh sách có ≥ 2 task, hỏi PM có muốn gộp dưới 1 ticket cha không — tạo mới / dùng sẵn / không cần (skill § 5.6b).
+7. Tạo ticket bằng `ak tasks create-tickets <file>.json --json` (skill § 5.7), kèm `parentTicket` nếu Bước 6 xác định có. Nếu thiếu WRITE credentials, hỏi PM nhập ngay trong chat rồi `ak credentials set <field> "<value>"` và thử lại đúng 1 lần. Nếu lỗi `parent-not-found`/`parent-create-failed`, hiển thị nguyên lỗi và hỏi PM muốn thử ticket cha khác, bỏ qua ticket cha, hay dừng lại.
+8. Ghi ngược link ticket vào entry gốc + hiển thị tổng kết (skill § 5.8).
 8. Run: `ak gate 3 approved --ticket [ticket-id]` để đóng task.
 
 > **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` chỉ khi Bước 2 kết luận CẦN task. Run `ak gate 3 approved --ticket [ticket-id]` khi Gate 3 hoàn tất, hoặc `ak gate 3 skip --ticket [ticket-id] --reason "..."` khi Bước 2 kết luận KHÔNG cần task.

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

@@ -59,6 +59,7 @@ DO NOT just check format — **understand the data and propose solutions**.
 Only runs after Gate 2 has been APPROVED.
 
 **INVOKE:** `train-model` skill
+- **Framework rules (bắt buộc, đọc trước dòng code đầu tiên):** nếu chưa đọc trong session này, đọc đầy đủ file(s) được trỏ ở dòng "> **Rules & code examples:**" đầu CLAUDE.md/AGENTS.md (`.rules/<lang>/<framework>-rules.md` + `-examples.md`). Áp dụng cho MỌI lần sửa code trong Gate này, không chỉ lần đầu.
 - For algorithm-optimization tickets EXTRA: `improve-algorithm` skill
 
 **Eval-harness-first rule:** Write the metric/eval harness and establish a reproducible baseline BEFORE iterating on the model. Confirm the baseline runs and is logged — then proceed with tracked experiments.