@relipa/ai-flow-kit 0.1.8 → 0.1.9

package/README.md

@@ -29,7 +29,7 @@ Developers only need a single command to load ticket context → AI automaticall
 - **[Quick Start Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
 - **[Full Workflow (5 Gates)](https://github.com/example/ai-flow-kit/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
 - **[Troubleshooting](https://github.com/example/ai-flow-kit/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
-- **[Integration Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Integration Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Codex, Cursor, Gemini).
 - **[Changelog](https://github.com/example/ai-flow-kit/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
 
 ---
@@ -289,13 +289,13 @@ ak execute
 3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence per `run-{N}/`, update TC file R1/R2 columns — QA reviews → `APPROVED`
 4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, ask per-bug Jira confirmation — QA reviews → `APPROVED`
 
-> **Multi-AI:** Works with Claude, Gemini, Cursor, Copilot — the execute-flow skill is loaded via `ak init`/`ak up`.
+> **Multi-AI:** Works with Claude, Codex, Gemini, Cursor, Copilot — the execute-flow skill is loaded via `ak init`/`ak up`.
 
 ---
 
 ### `ak sync-skills`
 
-Synchronize AI instruction files (`CLAUDE.md`, `GEMINI.md`, etc.) and Skills without upgrading the package version. 
+Synchronize AI instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, etc.), Skills, and Codex assets (`.codex/skills/`, `.codex/config.toml`) without upgrading the package version. 
 
 ```bash
 ak sync-skills
@@ -580,6 +580,7 @@ Then run `ak update` or `ak sync-skills` to apply.
 | Environment | Experience | Notes |
 |-----------|------------|---------|
 | Claude Code CLI (`claude`) | ⭐⭐⭐⭐⭐ | Full auto — skills, hook, automatically loaded context |
+| Codex — VS Code extension, ChatGPT desktop app, `codex` CLI | ⭐⭐⭐⭐ | `AGENTS.md` + auto-discovered `.codex/skills/` → `/ak-coding`. No session hook: start a new session after `ak use` |
 | Claude Extension (VS Code) | ⭐⭐⭐ | `ak prompt <type>` → copy paste |
 | Antigravity / Cursor | ⭐⭐⭐ | `ak prompt <type>` → copy paste |
 
@@ -589,6 +590,23 @@ Then run `ak update` or `ak sync-skills` to apply.
 
 > Summary of major changes per version. See full details in [CHANGELOG.md](docs/common/CHANGELOG.md).
 
+### v0.1.9 — 2026-08-04
+- **Codex (OpenAI) support — `ak init --env codex`:** One install covers all three local Codex surfaces, which share the same `CODEX_HOME` config, skills and MCP setup: the **VS Code extension**, **Codex mode in the ChatGPT desktop app**, and the **`codex` CLI**. Generates `AGENTS.md`, `.codex/skills/` (all kit skills, auto-discovered — the kit's `SKILL.md` layout is already Codex-compatible), `.codex/config.toml` (MCP servers mirrored from `.mcp.json`), and `.aiflow/instructions/`.
+- **Four Codex entry-point skills:** `/ak-coding`, `/ak-create-spec`, `/ak-create-testcase`, `/ak-ask` — the same workflows Claude Code exposes as slash commands.
+- **New "pointer" instruction-file layout:** Codex truncates the combined `AGENTS.md` chain at `project_doc_max_bytes` (32 KiB by default) and the full workflow set is ~115 KB, so inlining it the way `CLAUDE.md` does would silently cut instructions off mid-gate. `AGENTS.md` stays ~20 KB and links to `.aiflow/instructions/` instead. Existing tools are unaffected.
+- **`ak doctor` gained a Codex section:** checks `AGENTS.md` against the active byte budget, the skill mirror, the workflow files, and MCP drift between `.mcp.json` and `.codex/config.toml`.
+- **`ak remove` never deletes a hand-edited `.codex/config.toml`** — only one still carrying the `# ai-flow-kit managed` header. Same rule on write: an unmanaged config is left alone and the generated version goes to `.aiflow/reference/`.
+- Fixed (critical): **`ak init`/`ak update` duplicated instruction-file content on every run for multi-framework projects**, and silently dropped the first framework's rules — each framework now gets its own marker block, replaced in place on re-run.
+- Fixed: Gate 4/5 of the TESTER workflow pointed at `custom/skills/test-skills/...` paths that don't exist in a scaffolded project; `/coding` couldn't find the workflow under a pointer-layout instruction file.
+- Removed: `review-checklist.md` (+ ML/Java variants) — an unverified "tick each item" list at Gate 4 that no CLI ever enforced. The `gate-review` checkbox mechanism that `ak review check` does enforce is untouched.
+
+### v0.1.8 — 2026-07-24
+- **`aiflow-help` skill — the AI can now answer questions about ai-flow-kit itself:** install/setup, roles, `AK-Docs` structure, CLI commands, the memory workflow. Triggers on an `AKQ:`/`[AKQ]:` prefix or a kit-usage question even with no ticket loaded, answers from `docs/common/INDEX.md` with the source file cited, and says plainly when a topic isn't documented instead of guessing.
+- **`ak ask "<question>"`:** deterministic local keyword search across `docs/common/*.md` — no LLM, no network. Headings are weighted above body text; prints the top matches with the nearest heading and a snippet. Useful on Cursor/Gemini CLI, which have no semantic skill routing.
+- **`/ak-ask "<question>"`:** explicit slash command for when a natural-language question would otherwise be mistaken for ticket work.
+- **6 docs promoted `docs/internal/` → `docs/common/`:** `Project-Structure.md`, `BA-Specs-Structure.md`, `Coding-Structure.md`, `Testing-Structure.md`, `Memory-Architecture-v1.0.md`, `Docs-Management-Flow.md` — now shipped to every project via `.aiflow/docs/`, which is what makes the folder-structure questions answerable at all.
+- Fixed: **`ak update` never refreshed `.aiflow/docs`** — it synced rules, framework files and commands but never called `copyDocsToProject`. Projects initialized before this release only got new docs by re-running `ak init`.
+
 ### v0.1.7 — 2026-07-20
 - **`99.Memory/` Project Brain (Phase 1):** New git-based, human-approved team knowledge base in `AK-Docs/99.Memory/` — replaces the dead `.aiflow/memory/` JSON store. AI drafts lessons/facts/decisions locally; a human submits them via Merge Request, PM approves.
 - **`ak memory draft|list|submit|remove`:** New CLI (`scripts/memory-store.js` + rewritten `scripts/memory.js`), reusing the same branch-then-MR pattern as `ak docs branch`/`ak docs submit`.

package/bin/aiflow.js

@@ -137,7 +137,7 @@ program
     .description('Initialize AI Flow Kit in your project')
     .option('-f, --framework <types>', 'framework(s), comma-separated (e.g. spring-boot,reactjs)')
     .option('-a, --adapter <types>', 'adapter(s), comma-separated (e.g. backlog,jira)')
-    .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
+    .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated: claude,cursor,gemini,copilot,codex')
     .option('--with-rtk', 'force enable RTK token compression hook')
     .option('--no-rtk', 'skip RTK setup even if RTK is detected')
     .action((options) => {
@@ -626,7 +626,7 @@ program
     .description('Manually synchronize AI Instruction files with local custom skills')
     .action(async () => {
         const projectDir = process.cwd();
-        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored, setupClaudeCommands } = require('../scripts/init');
+        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored, setupClaudeCommands, setupCodex } = require('../scripts/init');
         const fs = require('fs-extra');
         const path = require('path');
         const chalk = require('chalk');
@@ -647,6 +647,7 @@ program
             await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools, { force: true });
         }
         await setupClaudeCommands(projectDir);
+        await setupCodex(projectDir, selectedTools);
         await ensureAiflowGitignored(projectDir);
         console.log(chalk.green('✨ Sync completed!'));
     });

package/custom/rules/ml-conventions.md

@@ -86,6 +86,5 @@ Before saving any ML plan, experiment plan, or eval report, verify:
 
 ## Other Conventions
 
-- **ML review checklist:** `custom/rules/ml-review-checklist.md`
 - **Code style:** `custom/rules/code-style.md`
 - **Naming:** `custom/rules/naming.md`

package/custom/rules/project-conventions.md

@@ -77,7 +77,6 @@ Before saving any requirement, plan, TDD-notes, review, or PR file, verify:
 
 ## Other Conventions
 
-- **Review checklist:** `custom/rules/review-checklist.md`
 - **Code style:** `custom/rules/code-style.md`
 - **Naming:** `custom/rules/naming.md`
 - **Folder structure reference:** `docs/common/Coding-Structure.md` · `docs/common/Project-Structure.md`

package/custom/skills/generate-spec/SKILL.md

@@ -34,6 +34,8 @@ When updating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` in **fas
 
 Read `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` — use the chosen approach, file list, and testing plan as input.
 
+Also read **Section 2 (Dependency Map)** and **Section 4 (Impact Analysis)** — do NOT re-run dependency investigation, Gate 1 already collected it. Carry every area flagged 🟡 Medium / 🔴 High / ⛔ Critical into Step 2's task breakdown (see below).
+
 ### Step 1.5: Read Design Context (if present)
 
 If `plan/[ticket-id]/design/design-context.md` exists (UI ticket from Gate 1):
@@ -65,6 +67,7 @@ Create a detailed step-by-step plan based on the requirement document:
 | 2 | Implement [component] | [source file] | — | Task 1 |
 | 3 | Write test for [scenario] | [test file] | ✅ | Task 2 |
 | ... | ... | ... | ... | ... |
+| N | Update/verify dependent [Caller X] (impact: 🟡/🔴/⛔) | [dependent file] | ✅ | [task that changes the shared symbol] |
 
 ### Test Commands
 ```bash
@@ -74,6 +77,8 @@ Create a detailed step-by-step plan based on the requirement document:
 
 > For UI tasks, reference the exact node/component from `design-context.md` in the Task column
 > (e.g. "Build UserCard — nodeId 78-910"). Add an image-copy task when the Image Map is non-empty.
+>
+> For every dependency in requirement.md Section 4 flagged 🟡 Medium / 🔴 High / ⛔ Critical, add one task per affected caller/dependent (update it, or add/extend a regression test) — placed right after the task that changes the shared symbol they depend on.
 
 ### Step 3: GATE 2 — Present Plan & Start Coding
 
@@ -115,4 +120,6 @@ Type feedback to adjust the plan.
 - ✅ **MUST** use TDD order: test first, then implementation
 - ✅ **MUST** invoke `superpowers:writing-plans` for plan creation
 - ✅ **MUST** show clear task breakdown before getting approval
+- ✅ **MUST** include a task for every dependency flagged 🟡 Medium / 🔴 High / ⛔ Critical in Gate 1's Impact Analysis (Section 4)
+- ❌ **DO NOT** re-run dependency-map investigation — reuse Gate 1's Dependency Map (Section 2) as-is
 - ❌ **DO NOT** include `git commit`, `git add`, or any git operations in the plan. The developer manages commits manually.

package/custom/skills/read-study-requirement/SKILL.md

@@ -107,7 +107,12 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
      - `gitnexus: query("keyword or description")` → hybrid search across codebase
      - Saves ~50% of token cost at this step vs reading files manually
    - **If task is a Bug Fix:** Invoke `superpowers:systematic-debugging` to trace root cause before proposing fixes.
-5. Read ticket comments — additional context from PM/team
+5. **Map Dependencies (Impact Investigation).** For each file identified in step 4 as directly affected, find all callers/dependents — apply `impact-analysis` skill **Step 1** (Find all usage):
+   - **If GitNexus MCP available:** `gitnexus: impact("ClassName")` → blast radius (callers, dependents, risk score). One call replaces the grep commands below.
+   - **Fallback — grep:** search callers/importers of the class/function across the project's languages; check Jobs/Events/Crons calling it indirectly; Frontend components calling related APIs; Tests mocking/stubbing the class.
+   - Keep the resulting list of callers/dependents — it feeds Step 3 (Impact Analysis) below. Do not classify risk level yet, only collect the dependency list.
+   - This step only runs in `auto`/`full` mode — `fast` mode intentionally skips it (see Fast Track above).
+6. Read ticket comments — additional context from PM/team
 
 Do this investigation **before** asking any questions. Come prepared.
 
@@ -170,10 +175,31 @@ Run this only when the ticket touches UI. Skip entirely for non-UI tickets.
 
 ---
 
+### Step 1.75: Classify Facts, Assumptions & Gaps
+
+> Runs in `auto`/`full` mode only. Borrowed from `ba-skills` initial-analysis — structures the investigation before Q&A so questions target real unknowns instead of generic vagueness.
+
+Go through the ticket's requirements/acceptance criteria and, for each one, classify it as:
+- **Fact** — explicitly stated in the ticket or confirmed by reading the source code
+- **Assumption** — inferred from experience/context/existing patterns, not yet confirmed by the developer
+- **Gap** — information missing entirely (not stated, not derivable from code)
+
+While classifying, check each functional requirement against:
+- Are there input limits/format constraints?
+- What happens on empty/invalid input — any error message defined?
+- Is there an implicit business rule not written down?
+- What are the alternative/exception flows?
+
+Keep this as a working list (Fact / Assumption / Gap) — it drives which questions to ask in Step 2, and gets written into the requirement doc (Section 1).
+
+---
+
 ### Step 2: Clarify Requirements via Q&A
 
 Ask clarifying questions directly — **one question at a time**, wait for the developer's response before asking the next.
 
+**Prioritize questions that resolve unconfirmed Assumptions and Gaps from Step 1.75** over generic vague points — this keeps the Q&A focused on real unknowns.
+
 **When to ask:**
 - Business requirements are vague or ambiguous
 - Acceptance criteria are not measurable
@@ -196,13 +222,13 @@ Once you have sufficient clarity, propose **2–3 solution approaches** with tra
 
 ### Step 3: Extend with Impact Analysis & Effort Estimate
 
-After the developer confirms the design direction (Step 2), extend with:
+After the developer confirms the design direction (Step 2), run full impact analysis on the dependency map gathered in Step 1 — apply `impact-analysis` skill **Step 2–3** (do not re-run Step 1, the dependency list is already collected):
 
 **Impact Analysis:**
-- Which services, modules, and jobs are affected?
-- Any breaking changes to APIs, DB schema, or shared components?
-- Risk level: 🟢 Low / 🟡 Medium / 🔴 High
-- Mitigation for each risk
+- Evaluate each aspect from the dependency map (`impact-analysis` skill Step 2 table): Database/Cache, Background Jobs, Import/Export, Permissions, API/Mobile, Tests
+- Classify impact level (`impact-analysis` skill Step 3): 🟢 Low (1 file, no deps) / 🟡 Medium (2–5 files, tests need update) / 🔴 High (6+ files, API breaking change, DB migration) / ⛔ Critical (payment, auth, data integrity)
+- List concrete breaking changes and a mitigation for each identified risk
+- Base every line on the actual callers/dependents found in Step 1 — not guesswork
 
 **Effort Estimate:**
 - Break down into tasks: tests, implementation, migration
@@ -239,6 +265,13 @@ Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 ### Context & Constraints
 [Environment, business rules, dependencies, deadlines]
 
+### Facts / Assumptions / Gaps
+| Type | Item | Resolution |
+|------|------|------------|
+| Fact | [explicit in ticket/code] | — |
+| Assumption | [inferred, not yet confirmed] | [confirmed by DEV in Q&A / still open] |
+| Gap | [missing info] | [resolved via Q&A / still open] |
+
 ---
 
 ## 2. Source Code Analysis
@@ -248,6 +281,13 @@ Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 |------|------|---------------|
 | [path] | [Controller/Service/...] | [what it does now] |
 
+### Dependency Map
+[From Step 1 impact investigation — callers/dependents of each affected file/class]
+
+| File / Class | Callers / Dependents | Found via |
+|--------------|----------------------|-----------|
+| [path or ClassName] | [list of callers, jobs, frontend components, tests] | GitNexus `impact()` / grep |
+
 ### Data Flow
 ```
 [Entry point] → [Service] → [Repository] → [DB/External]
@@ -297,11 +337,13 @@ Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 
 ## 4. Impact Analysis
 
-**Impact Level:** 🟢 Low / 🟡 Medium / 🔴 High
+> Based on the Dependency Map (Section 2) — apply `impact-analysis` skill Step 2–3.
+
+**Impact Level:** 🟢 Low / 🟡 Medium / 🔴 High / ⛔ Critical
 
 | Area | Impact | Reason |
 |------|--------|--------|
-| [Module] | 🟢 None / 🟡 Minor / 🔴 Major | [why] |
+| [Module / DB-Cache / Jobs / Import-Export / Permissions / API-Mobile / Tests] | 🟢 None / 🟡 Minor / 🔴 Major | [why, referencing dependents found in Section 2] |
 
 **Breaking Changes:**
 - [ ] None expected
@@ -381,10 +423,12 @@ Please review the requirement document.
 
 | Concern | Handled by |
 |---------|-----------|
+| Fact/Assumption/Gap breakdown | This skill (inline, borrowed from `ba-skills` initial-analysis) |
 | Q&A loop (one question at a time) | This skill (inline) |
 | Propose 2–3 solution approaches | This skill (inline) |
 | Root cause tracing (bug tasks) | `superpowers:systematic-debugging` |
-| Impact analysis | This skill |
+| Dependency map (find all usage) | `impact-analysis` skill Step 1 methodology (reused inline) |
+| Impact analysis (evaluate + classify) | `impact-analysis` skill Step 2–3 methodology (reused inline) |
 | Effort estimate | This skill |
 | requirement.md template & output | This skill |
 | Gate 1 APPROVED gate | This skill |
@@ -400,5 +444,8 @@ Please review the requirement document.
 - ❌ **DO NOT** skip impact analysis and effort estimate
 - ✅ **MUST** run `git status` + `git pull --ff-only` (Pre-flight) before reading source code, when working tree is clean
 - ✅ **MUST** read source code before Q&A begins
+- ✅ **MUST** (in `auto`/`full` mode) map dependencies (`impact-analysis` Step 1) for every file identified as affected, before Q&A — `fast` mode is exempt by design
+- ✅ **MUST** classify Facts/Assumptions/Gaps (Step 1.75) before asking Q&A questions, in `auto`/`full` mode
+- ❌ **DO NOT** write the Impact Analysis section from guesswork — it must be based on the Dependency Map found in Step 1
 - ✅ **MUST** save `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`
 - ✅ **MUST** display Gate 1 prompt and wait for `APPROVED`

package/custom/skills/review-plan/SKILL.md

@@ -26,10 +26,10 @@ keywords: review, code review, approve, summary, checklist
 
 Check `mode` in `.aiflow/context/current.json`:
 
-| Mode | Impact Analysis | Review Checklist | summary.md |
-|------|----------------|-----------------|-----------|
-| `fast` | Quick scan — reason from diff only | 3 items | Short format |
-| `full` | Full grep scan across codebase | 10 items | Full format |
+| Mode | Impact Analysis | summary.md |
+|------|----------------|-----------|
+| `fast` | Quick scan — reason from diff only | Short format |
+| `full` | Full grep scan across codebase | Full format |
 
 ### Fast Track Impact Analysis (mode: fast)
 Assess impact by reasoning about the changed files only:
@@ -38,11 +38,6 @@ Assess impact by reasoning about the changed files only:
 3. If yes → list them and assign impact level
 4. DO NOT run grep on the full codebase
 
-### Fast Track Review Checklist (mode: fast)
-- [ ] All tests pass
-- [ ] No hardcoded credentials or secrets
-- [ ] No SQL injection risk in new queries
-
 ## Fast Mode Output Rules (CRITICAL)
 
 When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` in **fast mode**:
@@ -72,9 +67,6 @@ Run in the following mandatory order:
 
 2. impact-analysis skill
    → Check for breaking changes and side effects.
-
-3. review-checklist (.rules/review-checklist.md)
-   → Tick each item in the checklist.
 ```
 
 **If any step fails → fix first, do not proceed to Step 2.**
@@ -149,19 +141,6 @@ Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 - [File/Service A] — [reason for impact / lack of impact]
 
 **Breaking changes:** None / [description if any]
-
----
-
-## Review Checklist
-
-- [ ] Code compiles and all tests pass
-- [ ] No hardcoded credentials / config
-- [ ] Security: no SQL injection, no exposure of sensitive data
-- [ ] Impact Analysis has been run
-- [ ] Naming and Code Style follow conventions
-- [ ] Sufficient tests (unit + integration)
-- [ ] No dead code / leftover console.logs
-- [ ] UI matches `design-context.md` (layout, color, typography, spacing) — UI tickets only
 ```
 
 ### Step 2.5: Retrospect + propose memory drafts
@@ -192,7 +171,6 @@ Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 **Self-review results:**
 - Tests: ✅ [N] passed / ❌ [N] failed  
 - Impact: [Low/Medium/High]
-- Checklist: [N/N] items ✅
 - Memory drafts created: [N] (local, `_pending/` — `ak memory submit` when ready to share)
 
 **You need to:**

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

@@ -9,7 +9,9 @@
 2. Read `.aiflow/tasks/[taskId]/task-state.json` if it exists.
    - If `currentGate > 1` (task already in progress) → **resume at that gate** — do NOT restart from Gate 1. List which gates are already `APPROVED` before continuing.
    - Otherwise → start fresh at Gate 1.
-3. In this project's main AI instruction file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or `.github/copilot-instructions.md` — whichever is present), find the section **`## [DEV] 5-Gate Development Workflow`** and follow it exactly, beginning at the gate identified in step 2.
+3. Find the **`## [DEV] 5-Gate Development Workflow`** section and follow it exactly, beginning at the gate identified in step 2. Look in this order:
+   - `.aiflow/instructions/gate-workflow.md` — present when the instruction file links to the workflows instead of inlining them (Codex / `AGENTS.md` setups).
+   - Otherwise this project's main AI instruction file: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or `.github/copilot-instructions.md` — whichever is present.
 4. This workflow applies regardless of the ticket's `taskType` value — `bug-fix`, `feature`, `refactor`, `investigation`, and `documentation` all share this same 5-gate flow (see the "Workflow Selection" table above that section for the full routing).
 
 Do not wait for further confirmation from the developer before starting — begin the identified gate immediately.

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

@@ -156,7 +156,8 @@ Trước khi ghi bất kỳ file nào vào `02.BA-Specs/`, đảm bảo AK-Docs
 - Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
 - Nếu có `supplementaryContext[]` → đọc từng item (file đính kèm, ticket liên quan, comment PM)
 - Nếu có file yêu cầu thô được chỉ định → đọc file đó
-- **READ skill:** `.superpowers/skills/brainstorming/SKILL.md` (hoặc `brainstorming` skill) để chủ động làm rõ các yêu cầu thô, khơi gợi ý tưởng trước khi phân tích.
+
+> ❌ **KHÔNG** dùng `superpowers:brainstorming` ở gate này. Skill đó thiết kế cho thiết kế giải pháp kỹ thuật và có terminal state bắt buộc là invoke `writing-plans` (implementation plan) — sai bối cảnh cho BA workflow, vốn kết thúc Gate 1 bằng `Analysis_v1.md` + `QnA-Log_v1.md`, không phải code plan. Kỹ thuật "hỏi từng câu, đề xuất phương án" cần thiết đã có sẵn trong `skill-ba-qna` ở Bước 2/4 bên dưới.
 
 #### Bước 1b: Đọc Source Code
 
@@ -181,22 +182,35 @@ Nếu workspace mở dạng parent folder chứa cả `ak docs` lẫn source cod
 
 > ⚠️ Source code dùng để **hiểu hệ thống hiện tại** và phát hiện constraints kỹ thuật — giúp BA đặt câu hỏi chuẩn xác hơn và tránh đề xuất giải pháp mâu thuẫn với architecture. Business requirement vẫn đến từ stakeholder, không từ code.
 
-#### Bước 2: Phân tích yêu cầu và xác định Gaps
+#### Bước 2: Phân tích yêu cầu, xác định Gaps và hỏi làm rõ ngay (vòng lặp đồng bộ)
+
 - **READ skill:** `.claude/skills/ba-skills/skill-ba-phan-tich-ban-dau-v1.md` và làm theo
 - Phân biệt Facts (thông tin đã chốt) vs Assumptions (tự suy luận cần kiểm chứng)
 - Xem xét các khía cạnh: validate dữ liệu, định dạng nhập liệu, phân quyền, xử lý ngoại lệ, thông báo lỗi
-- Nếu có điểm mơ hồ cốt yếu → hỏi ONE câu làm rõ, đợi BA trả lời trước khi tiếp tục
+- Liệt kê **toàn bộ** Gap/Assumption tìm được — không chỉ những điểm "cốt yếu"
+
+**Vòng lặp hỏi-đáp:** Với từng Gap/Assumption trong danh sách, hỏi **ONE câu một lúc**, đợi BA trả lời trước khi hỏi câu tiếp theo:
+
+- BA trả lời đủ rõ → đánh dấu **Confirmed**, tích hợp ngay vào bản phân tích đang xây dựng, chuyển sang câu hỏi tiếp theo
+- BA trả lời "chưa biết" / "để hỏi lại [stakeholder]" / "chưa chốt được ngay" → đánh dấu **Open** (deferred), ghi chú lý do, vẫn chuyển sang câu hỏi tiếp theo — KHÔNG chặn cả vòng lặp lại vì một câu chưa trả lời được
+- Lặp lại cho tới khi **mọi** Gap/Assumption trong danh sách đã được hỏi (mỗi câu ở trạng thái Confirmed hoặc Open tường minh)
+
+Chỉ sau khi vòng lặp này hoàn tất (không còn Gap nào **chưa được hỏi**) mới chuyển sang Bước 3. Số lượng câu hỏi Open còn lại sau vòng lặp này chính là input cho Gate 2.
 
 #### Bước 3: Soạn thảo Kết quả phân tích sơ bộ
 - **READ template:** `.claude/skills/ba-skills/skill-ba-initial-analysis-template-v1.md`
-- Điền đầy đủ các mục theo template: Actors, Facts, Assumptions, Gap Analysis table
+- Điền đầy đủ các mục theo template: Actors, Facts, Assumptions, Gap Analysis table — dùng câu trả lời **Confirmed** từ vòng lặp Bước 2 làm nội dung chính, không phải giả định của AI
+- Gap Analysis table chỉ còn liệt kê các Gap **Open** (deferred) từ vòng lặp Bước 2
 - Lưu: `02.BA-Specs/01.Analysis/[functionId]/Analysis_v1.md`
 
 #### Bước 4: Soạn thảo danh sách Q&A
+
 - **READ skill:** `.claude/skills/ba-skills/skill-ba-qna-v1.md`
 - **READ template:** `.claude/skills/ba-skills/skill-ba-qna-template-v1.md`
-- Chuyển từng Gap thành câu hỏi cụ thể, khách quan, không định hướng
-- Mỗi câu hỏi tương ứng với ít nhất một Gap. Trạng thái ban đầu: **Open**
+- Ghi lại **toàn bộ** câu hỏi đã hỏi ở vòng lặp Bước 2 dưới dạng log: mỗi câu kèm câu trả lời và trạng thái cuối cùng
+  - **Confirmed** — BA đã trả lời trong Bước 2, ghi kèm câu trả lời
+  - **Open** — BA đã xác nhận chưa trả lời được ngay (cần hỏi lại stakeholder khác), ghi kèm lý do deferred
+- Không tạo câu hỏi mới ở bước này — đây là bản ghi (log) của vòng lặp đã chạy ở Bước 2, không phải một vòng hỏi mới
 - Lưu: `02.BA-Specs/02.QnA/[functionId]/QnA-Log_v1.md`
 
 #### Bước 5: Gate Review & Pause
@@ -471,7 +485,7 @@ Sau khi Gate 4 đã APPROVED (UC Spec hoàn thành):
 
 | Gate | Skills đọc | Output |
 |---|---|---|
-| Gate 1 | `brainstorming`, `skill-ba-initial-analysis`, `skill-ba-initial-analysis-template`, `skill-ba-qna`, `skill-ba-qna-template` | `Analysis_v1.md`, `QnA-Log_v1.md` |
+| Gate 1 | `skill-ba-initial-analysis`, `skill-ba-initial-analysis-template`, `skill-ba-qna`, `skill-ba-qna-template` | `Analysis_v1.md`, `QnA-Log_v1.md` |
 | Gate 2 | `skill-ba-qna`, `skill-ba-initial-analysis` | `Analysis_v(n+1).md`, `QnA-Log_v(m+1).md` (nếu còn Open) |
 | Gate 3 | `skill-ba-ui-prototype` | `UI-Prototype_v1.html` |
 | Gate 4 | `skill-ba-write-uc-spec`, `skill-ba-uc-template`, `skill-ba-mermaid-flowchart`, `skill-ba-build-business-rules` | `UC-Spec_v1.md` |
@@ -482,6 +496,8 @@ Sau khi Gate 4 đã APPROVED (UC Spec hoàn thành):
 
 - ❌ **KHÔNG** bỏ qua thứ tự Gate — luôn đi từ Gate 1 → 2 → 3 → 4
 - ❌ **KHÔNG** tự chốt giả định nghiệp vụ mà không đưa vào Q&A
+- ❌ **KHÔNG** dùng `superpowers:brainstorming` ở Gate 1 — terminal state của skill đó invoke `writing-plans`, bypass cấu trúc BA workflow
+- ✅ **BẮT BUỘC** ở Gate 1 Bước 2: hỏi hết **toàn bộ** Gap/Assumption xác định được, từng câu một, ngay trong hội thoại — không giới hạn ở "điểm mơ hồ cốt yếu". Chỉ được ghi Open (deferred sang QnA-Log) khi BA xác nhận rõ ràng là chưa trả lời được ngay
 - ❌ **KHÔNG** tiến Gate 3 khi vẫn còn câu hỏi Open
 - ❌ **KHÔNG chấp nhận APPROVED** ở Gate 1 hoặc Gate 2 khi còn bất kỳ câu hỏi nào trạng thái **Open** — từ chối và hiển thị danh sách câu hỏi cần trả lời
 - ✅ **BẮT BUỘC** chạy Bước 0 ở Gate 1 — xác nhận `functionId` và thư mục đầu ra trước khi làm bất cứ điều gì

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

@@ -180,8 +180,7 @@ Mandatory order:
 0. **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.
 1. `superpowers:verification-before-completion` — all tests must PASS
 2. `impact-analysis` skill — check for breaking changes
-3. Tick `custom/rules/review-checklist.md`
-4. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` — Test Results, Impact Analysis (files changed, affected features, breaking changes), Review Checklist
+3. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` — Test Results, Impact Analysis (files changed, affected features, breaking changes) — developer reviews manually before approving
 5. Update tracker row in `AK-Docs/04.Coding/00.Overview/_Index.md` (Gate 4 ✅)
 
 Then:
@@ -463,7 +462,7 @@ Coverage: [N]% acceptance criteria
 
 ### GATE 1 — Pre-flight & Work Plan (auto-start)
 
-**INVOKE:** `execute-flow` skill (from `custom/skills/test-skills/execute-flow/SKILL.md`)
+**INVOKE:** `execute-flow` skill (from `.claude/skills/execute-flow/SKILL.md`)
 
 **Đồng bộ Source & Docs (bắt buộc, chạy trước mọi pre-flight check khá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.
 
@@ -504,7 +503,7 @@ BASE_URL: [url]
 
 Only runs after Gate 1 APPROVED.
 
-**INVOKE:** `script-sync` skill (from `custom/skills/test-skills/script-sync/SKILL.md`)
+**INVOKE:** `script-sync` skill (from `.claude/skills/script-sync/SKILL.md`)
 
 **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.
 

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

@@ -78,8 +78,7 @@ Mandatory order:
 1. `superpowers:verification-before-completion` — eval runs must reproduce before any success claim
 2. `evaluate-model` skill — held-out metrics vs baseline and threshold, error analysis, overfitting/leakage/drift checks
 3. `impact-analysis` skill — assess data pipeline and downstream blast radius
-4. Tick `custom/rules/ml-review-checklist.md`
-5. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` with the eval report and a model card draft (own section in the same file)
+4. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` with the eval report and a model card draft (own section in the same file) — developer reviews manually before approving
 
 Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
 - Coding or pipeline bug → fix → repeat Gate 4.

package/custom/templates/tools/codex.md

@@ -0,0 +1,75 @@
+# Codex Agent Instructions (AGENTS.md)
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+This file is read by every local Codex surface — the **Codex IDE extension** (VS Code / Cursor / Windsurf), **Codex mode in the ChatGPT desktop app**, and the **`codex` CLI**. They share the same `CODEX_HOME` config, skills, and MCP setup, so the instructions below apply identically in all three.
+
+> **Important:** Codex has no session-start hook. At the beginning of **every** session, read `.aiflow/context/current.json` yourself to load the ticket context, then check `AK-Docs/04.Coding/` for existing progress before starting any task.
+
+Gate 1 does **not** auto-start under Codex. Wait for the developer to type **"start"**, **"Gate 1"**, **"Analyze ticket"**, or to run the `ak-coding` skill.
+
+## Where things live
+
+| What | Path | Notes |
+|------|------|-------|
+| Ticket context | `.aiflow/context/current.json` | Written by `ak use <TICKET>` |
+| Task progress | `AK-Docs/04.Coding/<section>/[functionId]/[ticketId].md` | Read before starting; never re-derive |
+| Team rules | `.rules/` | Language + common rules |
+| Full gate workflows | `.aiflow/instructions/` | See "Workflow instructions" below |
+| Skills | `.codex/skills/*/SKILL.md` | Project-level Codex skills |
+| Kit documentation | `.aiflow/docs/` | Start at `.aiflow/docs/INDEX.md` |
+
+## Workflow instructions — read on demand
+
+The complete gate workflows are **not inlined in this file**. Codex caps the combined
+`AGENTS.md` chain at `project_doc_max_bytes` (32 KiB by default) and the full workflow set is
+far larger, so it would be silently truncated mid-gate. Read the file you need from disk
+when you need it:
+
+- **DEV 5-Gate coding workflow** → `.aiflow/instructions/gate-workflow.md` (read this at Gate 1 and keep it open for the whole ticket)
+- **BA 4-Gate spec creation** → `.aiflow/instructions/create-spec-workflow.md`
+- **QA 4-Gate testcase creation** → `.aiflow/instructions/create-testcase-workflow.md`
+
+Read the relevant file **in full** before starting a gate. Do not work from memory of a
+previous session, and do not summarize a workflow file instead of following it.
+
+## Skills
+
+Project skills live in `.codex/skills/`. When a workflow step says **INVOKE:** `<skill-name>`,
+read `.codex/skills/<skill-name>/SKILL.md` and follow its instructions exactly.
+
+`.claude/skills/` holds a byte-identical copy of the same skills — `ak init` always
+writes it. If a workflow file names a `.claude/skills/...` path, read it as-is; it is the
+same file. Only `.codex/skills/` is auto-indexed by Codex.
+
+Four entry-point skills wrap the workflows above:
+
+| Skill | Use it for |
+|-------|-----------|
+| `ak-coding` | Start / resume the DEV 5-Gate coding workflow for the loaded ticket |
+| `ak-create-spec` | BA spec creation from a raw requirement |
+| `ak-create-testcase` | QA testcase creation from a requirement or spec |
+| `ak-ask` | Questions about ai-flow-kit itself |
+
+## Interaction Rules
+
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `.rules/project-conventions.md` if present. These rules override upstream skill defaults.
+- **NO AUTO-COMMIT:** Never `git commit`, `git push`, or `git reset --hard` unless the developer explicitly asks. Codex's approval modes do not substitute for this rule.
+
+## Asking about ai-flow-kit itself
+
+If the developer's message is prefixed with `AKQ:` or `[AKQ]:`, OR is a question about ai-flow-kit itself (install/setup, roles, folder structure, CLI commands, memory draft/submit, troubleshooting, switching AI tools) rather than the current ticket — even when no ticket context is loaded — do **not** start Gate 1. Instead follow `.codex/skills/aiflow-help/SKILL.md`.
+
+## Telemetry Command (detect once, use everywhere)
+
+Before the first gate, run this to detect the correct `ak` command for your environment:
+
+```bash
+command -v ak >/dev/null 2>&1 && echo "USE: ak" || echo "USE: ak.cmd"
+```
+
+Use whichever prints (e.g. `ak` on native Linux/macOS/Windows, `ak.cmd` on WSL without `ak` installed).
+All `ak gate ...` examples in the workflow files assume the detected command. Substitute accordingly.

package/docs/common/AIFLOW.md

@@ -93,6 +93,7 @@ claude                           # open Claude → AI auto-starts Gate 1
 >
 > **Tool Support:**
 > - **Claude Code:** AI auto-starts Gate 1 via SessionStart hook.
+> - **Codex (VS Code extension / ChatGPT desktop app / CLI):** Rules in `AGENTS.md`; no session hook, so start a new session after `ak use` and run `/ak-coding`.
 > - **Cursor:** Instructions in `.cursorrules` enforce the Gate Workflow.
 > - **Gemini CLI:** Rules in `GEMINI.md` guide the session.
 > - **Copilot:** Instructions in `.github/copilot-instructions.md`.
@@ -265,8 +266,7 @@ In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massi
 |------|--------|------------|
 | 1 | `superpowers:verification-before-completion` | All tests PASS |
 | 2 | `impact-analysis` skill | No breaking changes outside scope |
-| 3 | `custom/rules/review-checklist.md` | All items ticked |
-| 4 | Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` | File exists and is complete |
+| 3 | Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` | File exists and is complete — developer reviews manually before approving |
 
 **If any step fails → AI fixes it first, without showing DEV.**
 
@@ -481,6 +481,7 @@ One of the core strengths of `ai-flow-kit` is that the **Gate Workflow** is tool
 | Tool | File Name | Purpose |
 |------|-----------|---------|
 | Claude Code | `CLAUDE.md` | Primary rules for the CLI tool. |
+| Codex | `AGENTS.md` | Rules for the Codex IDE extension, ChatGPT desktop app, and CLI. Links to `.aiflow/instructions/` for the full workflows. |
 | Cursor AI | `.cursorrules` | Project-wide rules for Cursor. |
 | Gemini CLI | `GEMINI.md` | Context for Gemini sessions. |
 | Copilot | `.github/copilot-instructions.md` | Custom instructions for Copilot. |

package/docs/common/CHANGELOG.md

@@ -7,6 +7,48 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.1.9] - 2026-08-04
+
+### Added
+
+- **Codex (OpenAI) support — `ak init --env codex`.** One install covers all three local Codex surfaces, since they share the same `CODEX_HOME` config, skills and MCP setup: the **Codex IDE extension** (VS Code / Cursor / Windsurf), **Codex mode in the ChatGPT desktop app**, and the **`codex` CLI**. Generated artifacts:
+  - **`AGENTS.md`** — the instruction file Codex reads automatically at the repo root. Registered as the `codex` entry in `AI_TOOL_FILES` (`scripts/init.js`), so `ak update`, `ak sync-skills` and `ak remove` pick it up through the paths they already use.
+  - **`.codex/skills/`** — a mirror of `.claude/skills/`. Codex discovers any directory under it containing a `SKILL.md` with `name`/`description` frontmatter, which is the exact layout the kit's skills already use, so all 44 skills are indexed and auto-triggered with no rewriting. Four entry-point skills are added on top: `ak-coding`, `ak-create-spec`, `ak-create-testcase`, `ak-ask`.
+  - **`.codex/config.toml`** — project-scoped Codex config. MCP servers are mirrored from `.mcp.json` into `[mcp_servers.<id>]` tables (`command` / `args` / `env`), so Backlog, Jira, Figma and GitNexus work in Codex exactly as they do in Claude Code. Regenerated by `ak init`, `ak update` and `ak sync-skills` after adapters and GitNexus have registered their servers.
+  - **`.aiflow/instructions/`** — `gate-workflow.md` (resolved per framework, so `python-ml` gets the ML variant), `create-spec-workflow.md` and `create-testcase-workflow.md`.
+
+- **Pointer layout for instruction files (`AI_TOOL_LAYOUT` / `resolveToolLayout()` in `scripts/init.js`).** Codex truncates the combined `AGENTS.md` chain at `project_doc_max_bytes` — **32 KiB by default** — and the assembled workflow set is ~115 KB, so inlining it the way `CLAUDE.md` does (132 KB for a React project) would have silently cut the instructions off mid-gate with no error. Tools are now either `inline` (all existing tools — unchanged behaviour) or `pointer` (Codex): a pointer-layout file carries the tool header, framework rules and a compact skill **name** list, then links to `.aiflow/instructions/` for the workflows themselves. Measured on a React project: `AGENTS.md` is 20 KB against a 32 KiB floor, versus 132 KB inlined.
+  - The skill **registry table** is also replaced by a name-only list for pointer tools — Codex already indexes every skill's name and description from `.codex/skills/`, so restating them cost ~11 KB of doc budget per turn for nothing.
+  - `.codex/config.toml` additionally raises `project_doc_max_bytes` to 128 KiB as headroom for multi-framework projects, which append one block per framework.
+
+- **`ak doctor` — Codex health section.** Runs when `codex` is among the project's configured tools. Verifies `AGENTS.md` exists and fits the *active* byte budget (parsed from `.codex/config.toml`, falling back to Codex's 32 KiB default), that `.codex/skills/` holds all four entry points, that the three `.aiflow/instructions/` workflow files are present, and that `.codex/config.toml` has not drifted from `.mcp.json`.
+
+### Changed
+
+- **`ak remove`** now deletes `.codex/skills/`, and `.codex/config.toml` **only when it still carries the `# ai-flow-kit managed` header** — a hand-edited config is left in place. `.codex/` itself is removed only if nothing of the developer's remains in it. The same rule applies on write: if `.codex/config.toml` exists without our header, `ak init` leaves it untouched and saves the generated version to `.aiflow/reference/codex-config.toml` to merge manually.
+- **`ak use`** next-steps output now lists Codex under both CLI and IDE, and warns that Codex has no session-start hook — a ticket loaded with `ak use` is only picked up by a **new** Codex session, otherwise run `/ak-coding` in the open one.
+- **`.gitignore`** gains `AGENTS.md` and `.codex/` via `ensureAiflowGitignored()`.
+- **`-e, --env`** help text now lists all five tools (`claude,cursor,gemini,copilot,codex`) in `bin/aiflow.js` and `ak guide --commands`.
+
+### Fixed
+
+- **Critical: `ak init` / `ak update` duplicated AI instruction file content on every run for multi-framework projects.** `setupFramework()` (`scripts/init.js`), when a project had 2+ frameworks selected (`state.frameworks.length > 1`), fell into a code path that blindly ran `fs.appendFile(targetPath, separator + frameworkContent)` on `CLAUDE.md` / `GEMINI.md` / `.cursorrules` / `.github/copilot-instructions.md` whenever the file already existed — with no marker or dedup check. Every `ak init`/`ak update` re-run re-appended each framework's conventions to the end of the file, so the file grew without bound run after run (confirmed via reproduction: 96,591 bytes → 112,699 bytes → unbounded across repeated runs). The same code path also silently **dropped the first selected framework's conventions entirely** (`if (!multi && frameworkContent)` excluded it whenever more than one framework was selected), so multi-framework projects never actually got that framework's rules written at all.
+  - **Fix:** each framework now gets its own self-contained marker block per tool file — `<!-- aiflow-kit-start:<framework> --> ... <!-- aiflow-kit-end:<framework> -->` — instead of an unmarked append. On re-run, if that framework's block already exists it is replaced in place via regex instead of appended again, mirroring the idempotent single-framework update path. Removed the `!multi` condition that excluded framework content from multi-framework output.
+  - No signature or call-site changes — `init.js`, `update.js`, and `bin/aiflow.js` all call `setupFramework()` the same way; only its internal multi-framework branch changed.
+  - Single-framework projects were never affected — that path already fully overwrote the marker block (with a `.aiflow/bk/` backup) on every run.
+
+- **Gate 4/5 of the TESTER workflow pointed at skill paths that do not exist in a scaffolded project.** `custom/templates/shared/gate-workflow.md` told the AI to read `custom/skills/test-skills/execute-flow/SKILL.md` and `custom/skills/test-skills/script-sync/SKILL.md` — both wrong twice over: `custom/` is the kit's own repo layout, not the project's, and neither skill lives under `test-skills/`. Corrected to `.claude/skills/execute-flow/SKILL.md` and `.claude/skills/script-sync/SKILL.md`, which is where `ak init` actually deploys them. This also unbreaks `tests/init-skill-paths.test.js`, which had been failing on exactly this.
+
+- **`/coding` could not find the workflow under a pointer-layout instruction file.** `custom/templates/shared/coding-workflow.md` step 3 only looked for the `## [DEV] 5-Gate Development Workflow` heading inside the instruction file itself; under Codex that section lives in `.aiflow/instructions/gate-workflow.md`. It now checks that path first and falls back to the instruction file.
+
+### Removed
+
+- **`review-checklist.md` / `ml-review-checklist.md` / `java/review-checklist.md`** — the plain-prose "tick each item" checklist read at Gate 4 (`review-plan` skill and every Gate-4 template). Unlike the `gate-review` skill's `.aiflow/review/gate-N-*.md` checkbox files — which `ak review check` actually parses and hard-blocks `APPROVED` on (unchecked items or unresolved comments) — this checklist had no CLI verification at all; the AI was only told to "tick" it, so nothing enforced that it was ever genuinely checked. Deleted all 3 files under `custom/rules/`, and removed every "Tick `custom/rules/review-checklist.md`" step from the Gate 4 mandatory order: `custom/templates/shared/gate-workflow.md` (DEV), `custom/templates/shared/ml-gate-workflow.md` (ML), `custom/skills/review-plan/SKILL.md` (also dropped its "Review Checklist" table column, the fast-mode 3-item checklist, and the summary's `Review Checklist` section + `Checklist: [N/N]` line), `scripts/prompt.js` (bug-fix/feature/refactor templates), and root `CLAUDE.md`. Cleaned up remaining mentions in `custom/rules/project-conventions.md`, `custom/rules/ml-conventions.md`, `AIFLOW.md`, `docs/common/AIFLOW.md`, and `docs/internal/{IMPLEMENTATION_SUMMARY,architecture,developer-overview}.md`.
+  - Gate 4 now ends with the AI creating the review/summary doc and the developer manually reading it before typing `APPROVED` or `BUG: ...` — no separate checklist artifact. The `gate-review` checkbox-enforcement mechanism itself is untouched and still runs at every gate of every workflow (DEV/TESTER/EXECUTE/BA/QA).
+  - Historical mentions in `plan/ml-skill-set/` and `upgrade-plan/` were left as-is (accurate at time of writing).
+
+---
+
 ## [0.1.7] - 2026-07-20
 
 ### Added