@relipa/ai-flow-kit 0.1.5 → 0.1.6

package/docs/common/CHANGELOG.md

@@ -9,6 +9,35 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.6] - 2026-07-13
+
+### Added
+
+- **Mandatory Source & Docs sync at the start of every Gate — across DEV, TESTER, EXECUTE, BA, and QA workflows.** Previously, `git pull` for `AK-Docs`/`Shared-Docs` only ran via the `ak init` / `ak update` CLI commands (`scripts/docs-repo.js`), and the source repo itself was only synced once — inside the DEV workflow's Gate 1 pre-flight bullet. Now every Gate of every workflow syncs both the source repo and the docs repos before doing anything else:
+  - **New shared procedure — "Pre-flight — Đồng bộ Source & Docs":** (1) `cd` into the source repo itself (not just the outer workspace) → `git status --porcelain`, then `git pull --ff-only` if the working tree is clean (skipped silently if dirty, diverged, or no remote tracking branch); (2) `cd` into `AK-Docs/` (sibling folder at workspace root) → `git pull`; (3) `cd` into `Shared-Docs/` (sibling folder at workspace root) → `git pull`; (4) `cd` back to the original working directory before continuing the gate.
+  - **Failure handling:** if any `git pull` in the procedure fails (conflict, no remote, network, etc.), the AI does **not** block or stop the workflow — it shows a `⚠️ CẢNH BÁO` warning to the user and continues the gate with the current local data.
+  - **`custom/templates/shared/gate-workflow.md`** — added the shared procedure once under the mandatory intro; wired a short pointer to it into every gate of all 3 workflows it defines: `[DEV]` 5-Gate (Gates 1–5), `[TESTER]` 4-Gate (Gate 1, Phases 2a/2b/2c/2d, Gates 3–4), and `[EXECUTE]` 4-Gate (Gates 1–4). The old DEV Gate 1 bullet that only synced the source repo now points at the shared procedure instead of duplicating a narrower version of it.
+  - **`custom/templates/shared/create-spec-workflow.md`** (`[BA]` 4-Gate Spec Creation) — added the shared procedure near the top and a pointer to it at the start of Gates 1–4.
+  - **`custom/templates/shared/create-testcase-workflow.md`** (`[QA]` 4-Gate TestCase Creation) — added the shared procedure near the top and a pointer to it at the start of Gates 1–4.
+  - If `AK-Docs/` or `Shared-Docs/` doesn't exist at the workspace root, or isn't a git repo, that step is skipped silently (no warning) — the project may not use a separate docs repo.
+- **New task type `gen-doc` — "Generate Document" 2-Gate flow** (`!34 feature/new_task_type`). A lighter flow for ad-hoc documentation tasks that don't need TDD/coding gates: Gate 1 (AI reads the request, plans the document — outline, scope, output format, sources) → APPROVED → Gate 2 runs immediately (generates the document, self-reviews, writes a task summary, then auto-closes the task — no Gate 3/4/5).
+  - `scripts/detect.js` — new keyword set (`gen-doc`, `generate doc`, `tạo tài liệu`, `flow document`, …) so free-text task descriptions can auto-detect this type.
+  - `scripts/use.js` — new picker entry "📝 Generate Doc 2 Gate" in the manual task-type selector.
+  - `scripts/task.js` — `gen-doc` capped at `maxGate = 2`; gate labels ("Generate Document" / "Done") and gate-history summary generation updated accordingly.
+  - `scripts/prompt.js` (`ak prompt gen-doc`) and `scripts/hooks/session-start.js` (auto-start + fast-mode messages) — new gen-doc-specific instructions.
+  - `custom/templates/shared/gate-workflow.md` — new `## gen-doc Task Type — 2-Gate Flow` section; `custom/rules/project-conventions.md` — new gen-doc output-path table; `docs/common/AIFLOW.md` / `cli-reference.md` — documented the flow and the new `ak p gen-doc` prompt type.
+  - Initial output paths were `plan/[ticket-id]/requirement.md` / `output.md` / `task-summary.md` — since relocated to `AK-Docs/04.Coding/`, see **Changed** below.
+- **Figma design integrated into the DEV Gate workflow (Gate 1→4)** (`!32 feature/figma-gate-workflow`). UI tickets now get Figma wired in automatically, no manual skill invocation:
+  - **Gate 1** (`read-study-requirement`) detects a Figma URL (ticket description / `supplementaryContext[]` / asks DEV once), fetches the design **exactly once** via Figma MCP, and caches the shared artifact `design/` (`design-context.md` with layout/tokens/component list/image map, `nodes.json` raw cache, `images/`, `figma-manifest.json`).
+  - **Gate 2** (`generate-spec`) reads the cached `design-context.md` (no second MCP call) and folds the component tree, design-token mapping, and an image-copy task into the TDD plan.
+  - **Gate 3** (`figma-to-component`, new **Gate mode**) reuses the cached `nodes.json`, copies images to `public/assets/figma/`, and generates the components — again without re-calling MCP.
+  - **Gate 4** (`review-plan`) adds a **Design Conformance Check**: compares the built UI against `design-context.md` region-by-region, against the actual rendered reference image, not just a text checklist (no-fabricate / no-omit / layout / color / typography / every component and image present).
+  - Refresh: typing "reload figma" re-fetches at Gate 1 and overwrites the cached `design/` artifact.
+  - **New anti-429 guard** — `scripts/hooks/figma-rate-limit.js`, a `PreToolUse` hook (installed by `scripts/init.js`) that throttles every `mcp__figma__*` call to 6 REST-call-units/60s (tunable via `FIGMA_RATE_LIMIT_UNITS`; `download_figma_images` counts as 3 units). It **sleeps rather than fails**, so calls are delayed, never dropped — needed because Figma rate-limits `get_figma_data`/image renders by **seat tier**, and a View/Collab-seat token gets only ~6 Tier-1 calls/**month** (effectively unusable) vs 10–20/min for a Dev/Full seat.
+  - `docs/common/workflows/figma.md` — documents the Gate-by-Gate table above, the shared `design/` artifact layout, and a new "Rate limits (429)" section (seat-tier budget table, `Retry-After` triage, troubleshooting entry for immediate 429s).
+- **`ak docs branch` / `ak docs submit`** — new CLI commands (`scripts/docs-branch.js`) so the AI can help create a `feature/<functionId>/<taskId>` branch in `AK-Docs`/`Shared-Docs` from `main` (`ak docs branch`) and commit + push + open a Merge Request (`ak docs submit --title ... --description ...`), auto-detecting GitLab/GitHub via the remote URL to run `glab mr create` / `gh pr create`, or falling back to a pre-filled manual MR link if neither CLI is installed. Both commands print the full plan and only perform any git write action when passed `--yes` — which the AI may only add after the developer has explicitly confirmed the plan in chat (otherwise, or with no interactive TTY, it's a no-op dry run). This keeps the same "AI never commits/pushes unasked" guarantee as the existing `block-git-write` hook, extended to a capability that hook can't cover.
+- **`docs/internal/Docs-Management-Flow.md`** — new internal doc formalizing the `AK-Docs` branch/MR workflow for every role: `main` is protected, PM-reviewed-and-merged only; every other role (BA/Dev/QA/TL) updates docs on a `feature/<functionId>/<taskId>` branch created from `main`; a step-by-step table makes explicit which steps are self-review (the authoring role) vs. the single mandatory PM-review-and-merge gate. Generalizes the branch/MR model `Memory-Architecture-v1.0.md` §5.1 designed for `99.Memory/` to all of `AK-Docs`.
+
 ### Fixed
 
 - **`aiflow prompt <type>` still emitted `plan/[ticket-id]/...` paths** — The 0.1.5 migration to `04.Coding/` (see below) updated `gate-workflow.md`, the skills, all 5 tool templates, and `session-start.js`, but missed `scripts/prompt.js`. Its `PROMPT_TEMPLATES` (used by `aiflow prompt feature|bug-fix|refactor|investigation|impact-analysis|testing|documentation` to build the copy-paste prompt for Cursor/Gemini/manual use) still hard-coded `Output plan/[ticket-id]/requirement.md` / `plan.md` / `summary.md`, contradicting the `custom/rules/project-conventions.md` override appended later in the same prompt — this was the root cause of `/plan` still appearing at the project root even on 0.1.5-beta.1. All 11 occurrences now point at the current `04.Coding/<section>/[functionId]/[ticketId].md` convention.
@@ -16,6 +45,9 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **`gen-doc` and ML workflow output relocated from `plan/[ticket-id]/` to `AK-Docs/04.Coding/`.** Both `gen-doc` (2-gate, added this version — see **Added** above) and the ML 5-gate workflow (`ml-gate-workflow.md`, pre-existing) still wrote to the legacy `plan/[ticket-id]/requirement.md` / `output.md` / `task-summary.md` / `ml-problem.md` / `experiment-plan.md` / `eval-report.md` paths that the 0.1.5 Dev-workflow migration deliberately left untouched. Per user decision, neither gets its own AK-Docs section — both now reuse the **same** `01.Requirements/02.Plans/03.TDD-Notes/04.Reviews` folders as the standard Dev workflow (gen-doc only ever populates the first two; ML uses all it needs through Gate 4, folding the model card into the Gate 4 review doc). Both workflows now also require the same mandatory `functionId` confirmation at Gate 1 that DEV/BA/QA already had, which neither had before. Updated: `custom/templates/shared/gate-workflow.md` (gen-doc section) and `ml-gate-workflow.md`, `custom/rules/project-conventions.md` and `ml-conventions.md` (output-path tables + legacy-path deprecation notice extended to cover these), `scripts/prompt.js` (gen-doc template) and `scripts/hooks/session-start.js` (gen-doc fast-mode text), and 4 ML skills (`design-experiment`, `evaluate-model`, `explore-data`, `frame-ml-problem`) whose completion checklists still hard-coded the old paths independent of the rules-file override.
+- **Branch/MR hooks wired into every workflow that writes to `AK-Docs`.** `create-spec-workflow.md` (BA), `create-testcase-workflow.md` (QA), `gate-workflow.md` (DEV + gen-doc), and `ml-gate-workflow.md` (ML) each now: (a) confirm `functionId`/`taskId` and create/checkout the `AK-Docs` branch `feature/[functionId]/[taskId]` **before** writing the first gate output (new Bước 0.5, right after the existing functionId pre-flight), and (b) at the final gate, submit that branch via `ak docs submit` — with the commit/MR title+description shown and explicitly confirmed by the user first — instead of the previous vague "lưu tài liệu lên remote (GitLab)" instruction. Every step is explicit that PM reviews and merges the MR; the authoring role never merges it themselves.
+
 - **DEV workflow output relocated to `AK-Docs/04.Coding/`** — Per `docs/internal/Project-Structure.md` / `Coding-Structure.md`, `04.Coding/` (and its BA/QA siblings `02.BA-Specs/`, `03.Testing/`, `00.Project-Overview/`) belong under the `AK-Docs/` docs repo (a sibling of the source repo, synced via `scripts/docs-repo.js`), not directly at the source repo root. Updated all references across `CLAUDE.md`, `custom/rules/project-conventions.md`, `custom/templates/shared/gate-workflow.md`, the 5 tool templates, the DEV skills (`read-study-requirement`, `generate-spec`, `review-plan`, `gate-review`), `docs/common/AIFLOW.md` / `ai-integration.md` / `workflows/{bug-fix,feature}.md`, `scripts/hooks/session-start.js`, and `scripts/prompt.js`. `scripts/task.js` now resolves the coding dir via `resolveDocsRepoPath(PROJECT_DIR, 'AK-Docs')` (from `docs-repo.js`) instead of hard-coding the path, so `findTaskDocs()` / `detectCurrentGate()` look under `AK-Docs/04.Coding/` first, with the legacy `plan/<taskId>/` folder (at the source repo root) still checked as a fallback.
 
 ## [0.1.5] - 2026-07-01

package/docs/common/cli-reference.md

@@ -262,6 +262,7 @@ ak t n -t PROJ-33                            # specify ticket  (--ticket)
 | `plan/<id>/requirement.md` | Gate 2 |
 | `plan/<id>/plan.md` | Gate 3 |
 | `plan/<id>/summary.md` | Gate 5 |
+| `plan/<id>/output.md` _(gen-doc)_ | Done (Gate 2 complete) |
 
 **Example workflow:**
 ```bash
@@ -316,6 +317,7 @@ ak p feature                                 # generate feature prompt
 ak p investigation                           # generate investigation prompt
 ak p refactor                                # generate refactor prompt
 ak p impact                                  # generate impact analysis prompt
+ak p gen-doc                                 # generate document generation prompt (2-gate)
 ak p -l                                      # list all prompt types  (--list)
 ak p bug-fix -o p.md                         # save to file  (--output)
 ak p bug-fix -L vietnamese                   # Vietnamese language  (--lang)
@@ -323,7 +325,7 @@ ak p bug-fix -d comprehensive                # comprehensive detail  (--detail)
 ```
 
 **Options:**
-- `<type>` — Prompt type (bug-fix, feature, investigation, refactor, impact, docs)
+- `<type>` — Prompt type (bug-fix, feature, investigation, refactor, impact, docs, gen-doc)
 - `-l, --list` — List available prompt types
 - `-o, --output <file>` — Save to file instead of printing
 - `-L, --lang <lang>` — Language (english, vietnamese)

package/docs/common/workflows/figma.md

@@ -1,105 +1,176 @@
-# Figma → Component Workflow
-
-Generate UI components directly from Figma designs using the `figma-to-component` skill.
-
----
-
-## Prerequisites
-
-Choose one adapter based on your setup:
-
-### Option A — REST API (recommended, no Desktop required)
-
-```bash
-ak init -a figma
-# Prompts for FIGMA_API_TOKEN
-```
-
-Get your token: [figma.com/settings](https://www.figma.com/settings) → Security → Personal access tokens → Create new token (File content: read).
-
-### Option B — Official Figma MCP (requires Figma Desktop app)
-
-```bash
-ak init -a figma-desktop
-# No token needed — uses Desktop app session
-```
-
-Requirements: Figma Desktop app installed and the target file open before invoking the skill.
-
----
-
-## Getting a Figma Node URL
-
-1. Open your file in Figma (browser or Desktop)
-2. Right-click on a frame or component → **Copy link to selection**
-3. The URL looks like:
-   ```
-   https://www.figma.com/design/FILEKEY/FileName?node-id=123-456
-   ```
-   - `FILEKEY` — the file identifier (between `/design/` and the next `/`)
-   - `node-id=123-456` — the specific frame or component to generate
-
-You can also link to the entire file (no `node-id`) to let the skill list available frames.
-
----
-
-## Trigger the Skill
-
-Paste the Figma URL into Claude Code with a generation request:
-
-```
-Generate component from this Figma frame:
-https://www.figma.com/design/XXXXX/App?node-id=123-456
-```
-
-```
-Implement the UserCard UI from Figma:
-https://www.figma.com/design/XXXXX/App?node-id=78-910
-```
-
-```
-Read Figma and generate component following my project conventions:
-https://www.figma.com/design/XXXXX/App?node-id=42-0
-```
-
----
-
-## What to Expect
-
-The skill outputs in this order:
-
-1. **Design Summary** — layout structure, color palette, typography scale used in the design
-2. **Component file** — complete code for your detected framework (React, Next.js App Router, Vue 3, or Angular)
-3. **Usage example** — how to import and use the component
-4. **Notes** — anything that couldn't be mapped 1:1 from Figma (custom fonts, unsupported effects, etc.)
-
-**Framework auto-detection order:**
-1. Read `CLAUDE.md` for framework identifier (`nextjs-app-router`, `reactjs`, `vue-nuxt`, `angular`)
-2. Scan project files (`app/` dir → App Router, `angular.json` → Angular, `nuxt.config.*` → Vue)
-3. Fallback → Next.js / React
-
----
-
-## Review Checklist
-
-After the component is generated, verify:
-
-- [ ] Layout matches Figma (flex direction, alignment, gap)
-- [ ] Colors are correct (Tailwind class or arbitrary value)
-- [ ] Typography matches (size, weight, line-height)
-- [ ] Spacing correct (padding, margin, gap)
-- [ ] Interactive states handled (`'use client'` in App Router, variants in React/Vue/Angular)
-- [ ] Images use correct component (`next/image` for Next.js, `<img>` for others)
-- [ ] `className` / `class` prop exposed for external overrides
-
----
-
-## Troubleshooting
-
-| Problem | Fix |
-|---|---|
-| `get_figma_data` tool not found | Run `ak init -a figma` to configure the MCP |
-| "Invalid API token" | Token expired — create a new one at figma.com/settings |
-| Wrong node generated | Check the `node-id` in the URL matches your selection in Figma |
-| Figma Desktop MCP not responding | Ensure Figma Desktop app is open with the file loaded |
-| Component uses wrong framework | Add framework to `CLAUDE.md` (e.g. `nextjs-app-router`) |
+# Figma → Component Workflow
+
+Generate UI components directly from Figma designs using the `figma-to-component` skill.
+
+---
+
+## Prerequisites
+
+Choose one adapter based on your setup:
+
+> **Which adapter?** The REST API is rate-limited **per seat** (see [Rate limits](#rate-limits-429)
+> below): a View/Collab seat gets only ~6 heavy calls per MONTH — effectively unusable.
+> - Token from a **Dev/Full seat** → Option A (REST) works fine with the batched strategy.
+> - Only a View/Collab seat, or design-heavy work (many frames, art-heavy exports) →
+>   prefer **Option B (Figma Desktop)** — it uses the local app session and consumes no REST quota.
+
+### Option A — REST API (no Desktop required; needs a Dev/Full-seat token)
+
+```bash
+ak init -a figma
+# Prompts for FIGMA_API_TOKEN
+```
+
+Get your token: [figma.com/settings](https://www.figma.com/settings) → Security → Personal access tokens → Create new token (File content: read). Create it from an account with a **Dev or Full seat** — a View/Collab seat's token is capped at ~6 Tier 1 calls/month.
+
+### Option B — Official Figma MCP (requires Figma Desktop app)
+
+```bash
+ak init -a figma-desktop
+# No token needed — uses Desktop app session
+```
+
+Requirements: Figma Desktop app installed and the target file open before invoking the skill.
+
+---
+
+## Getting a Figma Node URL
+
+1. Open your file in Figma (browser or Desktop)
+2. Right-click on a frame or component → **Copy link to selection**
+3. The URL looks like:
+   ```
+   https://www.figma.com/design/FILEKEY/FileName?node-id=123-456
+   ```
+   - `FILEKEY` — the file identifier (between `/design/` and the next `/`)
+   - `node-id=123-456` — the specific frame or component to generate
+
+You can also link to the entire file (no `node-id`) to let the skill list available frames.
+
+---
+
+## Trigger the Skill
+
+Paste the Figma URL into Claude Code with a generation request:
+
+```
+Generate component from this Figma frame:
+https://www.figma.com/design/XXXXX/App?node-id=123-456
+```
+
+```
+Implement the UserCard UI from Figma:
+https://www.figma.com/design/XXXXX/App?node-id=78-910
+```
+
+```
+Read Figma and generate component following my project conventions:
+https://www.figma.com/design/XXXXX/App?node-id=42-0
+```
+
+---
+
+## What to Expect
+
+The skill outputs in this order:
+
+1. **Design Summary** — layout structure, color palette, typography scale used in the design
+2. **Component file** — complete code for your detected framework (React, Next.js App Router, Vue 3, or Angular)
+3. **Usage example** — how to import and use the component
+4. **Notes** — anything that couldn't be mapped 1:1 from Figma (custom fonts, unsupported effects, etc.)
+
+**Framework auto-detection order:**
+1. Read `CLAUDE.md` for framework identifier (`nextjs-app-router`, `reactjs`, `vue-nuxt`, `angular`)
+2. Scan project files (`app/` dir → App Router, `angular.json` → Angular, `nuxt.config.*` → Vue)
+3. Fallback → Next.js / React
+
+---
+
+## Figma trong Gate workflow
+
+Khi làm việc theo quy trình 5 Gate (xem `CLAUDE.md`) với ticket liên quan UI, Figma được
+nối tự động — không cần gọi skill thủ công:
+
+| Gate | Vai trò Figma |
+|------|----------------|
+| **1** | `read-study-requirement` dò Figma URL trong ticket (hoặc hỏi DEV một lần), đọc design **một lần** qua MCP, lưu artifact `plan/[ticket-id]/design/` (design-context.md + images/ + nodes.json). |
+| **2** | `generate-spec` đọc `design-context.md` → đưa component tree, design tokens, danh sách ảnh vào plan TDD. |
+| **3** | `figma-to-component` chạy ở **Gate mode**: dùng lại cache `nodes.json`, copy ảnh sang `public/assets/figma/`, sinh component (không gọi lại MCP). |
+| **4** | `review-plan` đối chiếu UI đã code với `design-context.md`. |
+
+**Artifact dùng chung** — nguồn sự thật cho mọi Gate sau Gate 1:
+
+```
+plan/[ticket-id]/design/
+├── design-context.md   # layout, tokens, component list, image map
+├── images/             # ảnh export từ Figma
+└── nodes.json          # raw get_figma_data (cache)
+```
+
+**Refresh khi design đổi:** gõ "reload figma" → Gate 1 fetch lại, ghi đè `design/`, cập nhật `Fetched`.
+
+**Ticket không liên quan UI** hoặc không có Figma URL → toàn bộ nhánh Figma được bỏ qua.
+
+---
+
+## Review Checklist
+
+After the component is generated, verify:
+
+- [ ] Layout matches Figma (flex direction, alignment, gap)
+- [ ] Colors are correct (Tailwind class or arbitrary value)
+- [ ] Typography matches (size, weight, line-height)
+- [ ] Spacing correct (padding, margin, gap)
+- [ ] Interactive states handled (`'use client'` in App Router, variants in React/Vue/Angular)
+- [ ] Images use correct component (`next/image` for Next.js, `<img>` for others)
+- [ ] `className` / `class` prop exposed for external overrides
+
+---
+
+## Rate limits (429)
+
+Figma rate-limits the REST API by **endpoint tier × plan × seat** (since 2025-11-17).
+`get_figma_data` (file/nodes) and image renders share the same **Tier 1** bucket:
+
+| Seat of the token owner | Tier 1 budget (file / nodes / render images) |
+|---|---|
+| View / Collab | **~6 calls / MONTH** (any plan) |
+| Dev / Full — Starter | 10 / min |
+| Dev / Full — Professional | 15 / min |
+| Dev / Full — Organization+ | 20 / min |
+
+The fills-map endpoint (`/v1/files/:key/images`) is Tier 2 (25-100/min) — the skill prefers it.
+Downloading image bytes from the returned S3 URLs costs nothing.
+
+> **Measured on a free personal (Starter) account, 2026-07:** the API returned
+> `x-figma-rate-limit-type: low` with `retry-after ≈ 4 days` after only ~4 Tier 1 calls —
+> i.e. free accounts behave like the View/Collab monthly bucket, NOT 10/min. On a free
+> account, budget ONE batched fetch per design and cache everything; for anything heavier
+> use `figma-desktop` or a paid Dev/Full seat.
+
+**Client-side guard:** `ak init` installs a PreToolUse hook
+(`.claude/hooks/figma-rate-limit.js`) that throttles every `mcp__figma__*` call to
+6 REST-call units per 60s (safe under the 10/min Starter budget; `download_figma_images`
+counts as 3 units — it makes up to 3 REST calls internally). It sleeps instead of
+failing, so calls are delayed — never dropped. Tune with `FIGMA_RATE_LIMIT_UNITS`
+(e.g. `15` on a Professional plan).
+
+**When you hit a 429, read the `Retry-After` header:**
+
+- **≤ 60s** → per-minute bucket. Wait and retry once — this is normal on art-heavy frames.
+- **Hours/days, or `X-Figma-Rate-Limit-Type: low`** → per-seat quota. A new token on the same
+  account will NOT help. Fix: use a token from a Dev/Full seat, or switch to
+  `ak init -a figma-desktop`.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `get_figma_data` tool not found | Run `ak init -a figma` to configure the MCP |
+| "Invalid API token" | Token expired — create a new one at figma.com/settings |
+| `429` immediately / every session | Token from a View/Collab seat (~6 calls/month) — see [Rate limits](#rate-limits-429) |
+| Wrong node generated | Check the `node-id` in the URL matches your selection in Figma |
+| Figma Desktop MCP not responding | Ensure Figma Desktop app is open with the file loaded |
+| Component uses wrong framework | Add framework to `CLAUDE.md` (e.g. `nextjs-app-router`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {
@@ -65,4 +65,4 @@
       "<rootDir>/tests/**/*.test.js"
     ]
   }
-}
+}

package/scripts/create-score-excel.js

@@ -24,6 +24,25 @@ function norm(cmd) {
   return ALIAS_MAP[c] || c;
 }
 
+// ── Version helpers ─────────────────────────────────────────────────────────
+const CURRENT_VERSION = '0.1.4';
+
+function parseVersion(v) {
+  if (!v || v === '-' || v === '' || v.toLowerCase() === 'unknown') return null;
+  const core = v.split('-')[0]; // strip prerelease suffix, e.g. 0.1.5-beta.1 -> 0.1.5
+  const parts = core.split('.').map(n => parseInt(n, 10));
+  if (parts.some(n => Number.isNaN(n))) return null;
+  return parts;
+}
+
+function compareVersion(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const diff = (a[i] || 0) - (b[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
 // ── Parse log file ─────────────────────────────────────────────────────────
 function parseLog(filePath) {
   const lines = fs.readFileSync(filePath, 'utf-8').split(/\r?\n/);
@@ -39,17 +58,19 @@ function parseLog(filePath) {
     if (!user || user === '-' || user === '') continue;
 
     const timestamp = cols[0] || '';
+    const version = cols[5] || '';
     const command = cols[6] || '';
     const ticket = cols[9] || '';
 
     const date = timestamp.split(' ')[0]; // dd/MM/yyyy
 
     if (!users[user]) {
-      users[user] = { email: user, days: new Set(), events: 0, rawCmds: new Set(), gateCmds: [] };
+      users[user] = { email: user, days: new Set(), events: 0, rawCmds: new Set(), gateCmds: [], versions: new Set() };
     }
     const u = users[user];
     u.events++;
     if (date) u.days.add(date);
+    if (version.trim()) u.versions.add(version.trim());
 
     const cmd = norm(command);
     if (cmd) u.rawCmds.add(cmd);
@@ -130,6 +151,19 @@ const SCORE_LABELS = [
   'Sử dụng thường xuyên workflow',
 ];
 
+// ── Version status for a user ──────────────────────────────────────────────
+function getVersionStatus(u) {
+  const all = [...u.versions];
+  const parsed = all.map(v => ({ raw: v, parts: parseVersion(v) })).filter(v => v.parts);
+  if (parsed.length === 0) {
+    return { status: all.length ? 'unknown' : 'none', latest: null, all };
+  }
+  parsed.sort((a, b) => compareVersion(a.parts, b.parts));
+  const latest = parsed[parsed.length - 1];
+  const isOutdated = compareVersion(latest.parts, parseVersion(CURRENT_VERSION)) < 0;
+  return { status: isOutdated ? 'outdated' : 'ok', latest: latest.raw, all };
+}
+
 // ── Build summary row for each user ───────────────────────────────────────
 function buildRow(email, u) {
   const { events, days, rawCmds, gateCmds } = u;
@@ -198,12 +232,12 @@ function buildRow(email, u) {
     impactLabel: '',
     totalScore: score,
     notes,
+    versionStatus: getVersionStatus(u),
   };
 }
 
 // ── Excel writer ───────────────────────────────────────────────────────────
-async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
-  const workbook = new ExcelJS.Workbook();
+function writeExcel(rows, workbook, sheetLabel, fromLabel, toLabel) {
   const sheet = workbook.addWorksheet(`Score ${sheetLabel}`);
 
   sheet.columns = [
@@ -247,20 +281,23 @@ async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
   const hRow = sheet.addRow(HEADERS);
   hRow.height = 36;
   hRow.eachCell(cell => {
-    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4472C4' } };
+    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4F81BD' } };
     cell.font = { bold: true, color: { argb: 'FFFFFFFF' }, size: 11 };
     cell.alignment = { vertical: 'middle', horizontal: 'center', wrapText: true };
     cell.border = border;
   });
 
-  // Score → row color
+  // Score → row color (matches requirements/GetPoints-format.png)
   const COLORS = {
-    0: 'FFFFC7CE',
-    1: 'FFFFEB9C',
-    2: 'FFFFFFCC',
-    3: 'FFD9EAD3',
-    4: 'FF93C47D',
-    5: 'FF6AA84F',
+    0: 'FFFFFFFF',
+    1: 'FFF5F8EE',
+    2: 'FFEBF1DE',
+    3: 'FFD8E4BC',
+    4: 'FFC4D79B',
+    5: 'FF76933C',
+  };
+  const FONT_COLORS = {
+    0: 'FFFF0000',
   };
 
   rows.forEach((row, idx) => {
@@ -274,9 +311,11 @@ async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
     r.height = 20;
 
     const fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: COLORS[row.depthScore] || 'FFFFFFFF' } };
+    const fontColor = FONT_COLORS[row.depthScore] || 'FF000000';
     r.eachCell({ includeEmpty: true }, (cell, col) => {
       cell.border = border;
       cell.fill = fill;
+      cell.font = { color: { argb: fontColor } };
       cell.alignment = (col <= 4 || (col >= 9 && col <= 13))
         ? { vertical: 'middle', horizontal: 'center' }
         : { vertical: 'middle', horizontal: 'left', wrapText: false };
@@ -289,8 +328,81 @@ async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
   sheet.views = [{ state: 'frozen', ySplit: 2 }];
   sheet.autoFilter = { from: 'A2', to: 'N2' };
 
+  return sheet;
+}
+
+// ── Version warning sheet ───────────────────────────────────────────────────
+function writeVersionSheet(workbook, rows) {
+  const sheet = workbook.addWorksheet('Version Warning');
+  sheet.columns = [
+    { key: 'no', width: 5 },
+    { key: 'email', width: 30 },
+    { key: 'status', width: 16 },
+    { key: 'latest', width: 16 },
+    { key: 'allVersions', width: 30 },
+    { key: 'note', width: 50 },
+  ];
+
+  const border = {
+    top: { style: 'thin' }, left: { style: 'thin' },
+    bottom: { style: 'thin' }, right: { style: 'thin' },
+  };
+
+  sheet.addRow([`Cảnh báo phiên bản — Yêu cầu phiên bản hiện tại: ${CURRENT_VERSION}`]);
+  sheet.mergeCells('A1:F1');
+  const title = sheet.getCell('A1');
+  title.font = { bold: true, size: 13, color: { argb: 'FF1F3864' } };
+  title.alignment = { vertical: 'middle', horizontal: 'center' };
+  title.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD6DCE4' } };
+  sheet.getRow(1).height = 28;
+
+  const HEADERS = ['#', 'Email', 'Trạng thái', 'Phiên bản mới nhất', 'Các phiên bản dùng trong tuần', 'Ghi chú'];
+  const hRow = sheet.addRow(HEADERS);
+  hRow.height = 20;
+  hRow.eachCell(cell => {
+    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FF4F81BD' } };
+    cell.font = { bold: true, color: { argb: 'FFFFFFFF' }, size: 11 };
+    cell.alignment = { vertical: 'middle', horizontal: 'center', wrapText: true };
+    cell.border = border;
+  });
+
+  const warnings = rows.filter(row => row.versionStatus.status === 'outdated' || row.versionStatus.status === 'unknown');
+
+  const STATUS_LABEL = { outdated: 'CŨ HƠN', unknown: 'KHÔNG XÁC ĐỊNH', ok: 'OK', none: 'Không có dữ liệu' };
+  const STATUS_COLOR = { outdated: 'FFFFC7CE', unknown: 'FFFFEB9C' };
+
+  warnings.forEach((row, idx) => {
+    const vs = row.versionStatus;
+    const note = vs.status === 'outdated'
+      ? `Đang dùng ${vs.latest}, chưa cập nhật lên ${CURRENT_VERSION}`
+      : 'Không đọc được phiên bản (giá trị "-" hoặc "unknown") — cần kiểm tra lại';
+    const r = sheet.addRow([
+      idx + 1, row.email, STATUS_LABEL[vs.status], vs.latest || '-', vs.all.join(', ') || '-', note,
+    ]);
+    r.height = 20;
+    const fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: STATUS_COLOR[vs.status] || 'FFFFFFFF' } };
+    r.eachCell({ includeEmpty: true }, (cell, col) => {
+      cell.border = border;
+      cell.fill = fill;
+      cell.alignment = (col <= 4)
+        ? { vertical: 'middle', horizontal: 'center' }
+        : { vertical: 'middle', horizontal: 'left', wrapText: false };
+    });
+  });
+
+  sheet.views = [{ state: 'frozen', ySplit: 2 }];
+  sheet.autoFilter = { from: 'A2', to: 'F2' };
+
+  return warnings;
+}
+
+async function writeExcelFile(rows, outputPath, sheetLabel, fromLabel, toLabel) {
+  const workbook = new ExcelJS.Workbook();
+  writeExcel(rows, workbook, sheetLabel, fromLabel, toLabel);
+  const warnings = writeVersionSheet(workbook, rows);
   await workbook.xlsx.writeFile(outputPath);
-  console.log(`Written: ${outputPath} (${rows.length} users)`);
+  console.log(`Written: ${outputPath} (${rows.length} users, ${warnings.length} version warning(s))`);
+  return warnings;
 }
 
 // ── Canonical user list (fixed order) ─────────────────────────────────────
@@ -315,6 +427,10 @@ const CANONICAL_USERS = [
   'anhnt@relipasoft.com',
   'khanhdd@relipasoft.com',
   'hieunv@relipasoft.com',
+  'cucdt@relipasoft.com',
+  'khanhnv@relipasoft.com',
+  'namhh@relipasoft.com',
+  'tannt@relipasoft.com',
 ];
 
 // Log email → canonical email (for slight mismatches)
@@ -323,7 +439,7 @@ const LOG_EMAIL_ALIAS = {
 };
 
 const EMPTY_USER = (email) => ({
-  email, events: 0, days: new Set(), rawCmds: new Set(), gateCmds: [],
+  email, events: 0, days: new Set(), rawCmds: new Set(), gateCmds: [], versions: new Set(),
 });
 
 // ── Main ───────────────────────────────────────────────────────────────────
@@ -357,6 +473,7 @@ const EMPTY_USER = (email) => ({
       u.events += data.events;
       data.days.forEach(d => u.days.add(d));
       data.rawCmds.forEach(c => u.rawCmds.add(c));
+      data.versions.forEach(v => u.versions.add(v));
       u.gateCmds.push(...data.gateCmds);
     }
   }
@@ -367,5 +484,9 @@ const EMPTY_USER = (email) => ({
     return buildRow(email, u);
   });
 
-  await writeExcel(rows, outputFile, sheetLabel, fromLabel, toLabel);
+  const warnings = await writeExcelFile(rows, outputFile, sheetLabel, fromLabel, toLabel);
+  if (warnings.length) {
+    console.log(`\n⚠️  Version warnings (< ${CURRENT_VERSION} or unknown):`);
+    warnings.forEach(w => console.log(`  - ${w.email}: ${w.versionStatus.latest || 'unknown'} (${w.versionStatus.status})`));
+  }
 })();

package/scripts/detect.js

@@ -74,6 +74,17 @@ class TaskDetector {
                 antiKeywords: [],
                 icon: '🧪',
                 description: 'Writing tests and QA'
+            },
+            'gen-doc': {
+                keywords: [
+                    'gen-doc', 'generate doc', 'generate document', 'tạo tài liệu',
+                    'tài liệu flow', 'tài liệu logic', 'tài liệu điều tra',
+                    'flow document', 'logic document', 'analysis document',
+                    'source analysis', 'feature document', 'system document'
+                ],
+                antiKeywords: ['code', 'fix', 'bug'],
+                icon: '📝',
+                description: 'Generate document from source code / feature analysis'
             }
         };
     }