@relipa/ai-flow-kit 0.1.7 → 0.1.8-beta.0

package/README.md

@@ -459,7 +459,7 @@ ak validate src/Payment.java --ruleset strict
 
 ### `ak memory`
 
-Draft, submit, and remove entries in the `99.Memory/` Project Brain (`AK-Docs/99.Memory/`) — see [Memory-Architecture-v1.0.md](docs/internal/Memory-Architecture-v1.0.md). Drafts are local-only until submitted; PM reviews and merges the Merge Request before a memory becomes team-visible.
+Draft, submit, and remove entries in the `99.Memory/` Project Brain (`AK-Docs/99.Memory/`) — see [Memory-Architecture-v1.0.md](docs/common/Memory-Architecture-v1.0.md). Drafts are local-only until submitted; PM reviews and merges the Merge Request before a memory becomes team-visible.
 
 ```bash
 ak memory draft --category 01.Lessons/dev --function-id F-003_Payment \

package/bin/aiflow.js

@@ -14,6 +14,7 @@ const contextCommand  = require('../scripts/context');
 const promptCommand   = require('../scripts/prompt');
 const removeCommand   = require('../scripts/remove');
 const guideCommand    = require('../scripts/guide');
+const askCommand      = require('../scripts/ask');
 const telemetryCommand= require('../scripts/telemetry/cli');
 const taskCommand     = require('../scripts/task');
 const checkpointCommand = require('../scripts/checkpoint');
@@ -349,7 +350,7 @@ program
         });
     });
 
-// ── memory (99.Memory/ Project Brain — see docs/internal/Memory-Architecture-v1.0.md) ──
+// ── memory (99.Memory/ Project Brain — see docs/common/Memory-Architecture-v1.0.md) ──
 // Same "AI drafts — human approves via MR" pattern as `docs` below: drafts are local-only
 // (_pending/, gitignored) until `submit` opens a Merge Request for PM review.
 const memCmd = program.command('memory').alias('mem').description('Manage 99.Memory/ project knowledge (draft, list, submit, remove)');
@@ -396,7 +397,7 @@ memCmd
     .action((path, options) => { memoryCommand('remove', { ...options, _positional: [path] }); });
 
 // ── docs (branch + Merge Request workflow for AK-Docs/Shared-Docs) ─────
-// See docs/internal/Docs-Management-Flow.md — PM reviews & merges `main`;
+// See docs/common/Docs-Management-Flow.md — PM reviews & merges `main`;
 // every other role updates docs on feature/<functionId>/<taskId> from main.
 const docsCmd = program.command('docs').description('Branch & Merge Request workflow for AK-Docs/Shared-Docs (see Docs-Management-Flow.md)');
 
@@ -439,6 +440,15 @@ program
         guideCommand(options);
     });
 
+// ── ask ───────────────────────────────────────────────────────
+program
+    .command('ask <question>')
+    .description('Search ai-flow-kit docs for an answer about the kit itself (install, roles, memory, CLI...)')
+    .option('-n, --limit <n>', 'max number of results to show', '3')
+    .action((question, options) => {
+        askCommand(question, { limit: options.limit });
+    });
+
 // ── telemetry feedback helper ─────────────────────────────────
 function showTelResult(result, label) {
     try {

package/custom/rules/project-conventions.md

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

package/custom/skills/aiflow-help/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: aiflow-help
+description: Answers questions about ai-flow-kit itself (install, roles, folder structure, CLI commands, memory draft/submit, troubleshooting) — trigger on install/setup/how-do-I-use-this/roles/folder-structure/memory-submit questions or an AKQ:/[AKQ]: prefix, even with no active ticket; skip for actual coding/ticket work. Read docs/common/INDEX.md first, cite the file used, and say plainly if a topic isn't documented instead of guessing.
+keywords: aiflow, ai-flow-kit, ak, install, cai dat, huong dan, PM, role, folder structure, thu muc, memory, submit memory, cli, commands, AKQ, how to use, huong dan su dung
+---
+
+# AI Flow Kit — Self-Help
+
+Answers questions **about ai-flow-kit itself** — not about the ticket/feature the developer is currently building. Examples: "how do I install this", "I'm a PM, how do I use ai kit", "give me an overview of the folder flow", "how do I manually create and submit a memory".
+
+## When this applies
+
+- The message is prefixed with `AKQ:` or `[AKQ]:` — always treat it as a self-help question, whatever else it contains.
+- Or the message asks about install/setup, roles (PM/DEV/AI), folder/`AK-Docs` structure, CLI commands, the `99.Memory/` workflow, switching between Claude Code/Cursor/Gemini, or troubleshooting — **even when there is no active ticket** in `.aiflow/context/current.json`.
+- Does **not** apply to requests to analyze, implement, fix, or review an actual ticket/feature — that's the Gate Workflow's job, not this skill's.
+
+## What to do
+
+1. Do **not** auto-start Gate 1 for this turn — this is a support question, not a coding task.
+2. Read `docs/common/INDEX.md` (in a scaffolded project this is copied to `.aiflow/docs/INDEX.md`; inside the ai-flow-kit repo itself it's `docs/common/INDEX.md`).
+3. Match the question against the "Ask about" table and read the linked doc file(s) — don't answer from memory of what ai-flow-kit "probably" does; the CLI's actual sub-commands and options change between versions (check `CHANGELOG.md` if anything looks stale).
+4. Answer directly and concisely, in whatever language the user asked in. Cite the file path you read from (e.g. "per `docs/common/cli-reference.md`").
+5. If the topic is listed under INDEX.md's "Unanswered topics", or isn't covered anywhere: say plainly it isn't documented yet, point to the closest related doc, and suggest `ak guide` (quickstart + command reference) or `ak ask "<question>"` (local keyword search across the docs) as a fallback. Never invent a command, flag, or file path that you haven't actually read.
+
+## After answering
+
+Stay in this mode for follow-up questions in the same vein. Only return to the normal Gate Workflow once the developer starts talking about an actual ticket/feature again.

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

@@ -166,7 +166,7 @@ Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 
 ### Step 2.5: Retrospect + propose memory drafts
 
-Synthesize what was learned this task. **Priority order — human corrections first:** if this is a repeat pass through Gate 4 (the developer already sent "BUG: ..." at least once this task), the developer's own correction is the single highest-value lesson — scan back through this session for it and draft it even if you already drafted something for the earlier BUG at Step 4 (dedup will catch an exact repeat; don't skip capturing it out of caution). Only after that, add anything else genuinely new: architecture facts discovered, decisions made and why. For each candidate, create a **local draft** (no approval needed yet — `_pending/` is local-only, doc `docs/internal/Memory-Architecture-v1.0.md`):
+Synthesize what was learned this task. **Priority order — human corrections first:** if this is a repeat pass through Gate 4 (the developer already sent "BUG: ..." at least once this task), the developer's own correction is the single highest-value lesson — scan back through this session for it and draft it even if you already drafted something for the earlier BUG at Step 4 (dedup will catch an exact repeat; don't skip capturing it out of caution). Only after that, add anything else genuinely new: architecture facts discovered, decisions made and why. For each candidate, create a **local draft** (no approval needed yet — `_pending/` is local-only, doc `docs/common/Memory-Architecture-v1.0.md`):
 
 ```
 ak memory draft --category 01.Lessons/dev --function-id [functionId] \

package/custom/templates/memory/skeleton/MEMORY.md

@@ -4,4 +4,4 @@
 > **Do not edit this file by hand** — it is rebuilt from the frontmatter of every `status: approved` file under `99.Memory/`.
 > One line per memory: `- [mem-id](path/to/file.md) — <hook ≤15 từ> (type, scope, workflows)`
 
-See `docs/internal/Memory-Architecture-v1.0.md` in ai-flow-kit for the full design.
+See `.aiflow/docs/Memory-Architecture-v1.0.md` in this project (or `docs/common/Memory-Architecture-v1.0.md` in the ai-flow-kit repo) for the full design.

package/custom/templates/shared/ak-ask-workflow.md

@@ -0,0 +1,15 @@
+## /ak-ask — Ask a Question About ai-flow-kit Itself
+
+**Why this command exists:** the `aiflow-help` skill normally triggers on keyword match or an `AKQ:` / `[AKQ]:` prefix, but that detection can be missed or ambiguous — especially when a question about ai-flow-kit's own usage (install, roles, folder structure, CLI, memory workflow) is phrased in a way that overlaps with real ticket work. `/ak-ask` is an explicit, unambiguous trigger: whatever follows is a self-help question about the kit, not the developer's current ticket.
+
+**Question:** $ARGUMENTS
+
+**Steps — do these now, in order:**
+
+1. Do **not** treat this as ticket/coding work — do not touch `.aiflow/context/current.json` or start any Gate.
+2. Read the topic index — `docs/common/INDEX.md` (inside the ai-flow-kit repo itself) or `.aiflow/docs/INDEX.md` (in a scaffolded project).
+3. Match the question above against the "Ask about" table in that index, and read the linked doc file(s). Don't answer from memory of what ai-flow-kit "probably" does — CLI sub-commands and options change between versions (check `docs/common/CHANGELOG.md` if anything looks stale).
+4. Answer directly and concisely, in whatever language the question was asked in. Cite the file path you read from (e.g. "per `docs/common/cli-reference.md`").
+5. If the topic is listed under INDEX.md's "Unanswered topics", or isn't covered anywhere: say plainly it isn't documented yet, point to the closest related doc, and suggest `ak guide` (quickstart + command reference) or `ak ask "<question>"` (local keyword search across the docs, run from the terminal) as a fallback. Never invent a command, flag, or file path you haven't actually read.
+
+Stay in this self-help mode for follow-up questions in the same vein; return to normal Gate Workflow once the developer starts talking about an actual ticket/feature.

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

@@ -443,7 +443,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 
 #### Bước 7.5: Retrospect + đề xuất memory draft
 
-Sau khi Gate 4 APPROVED, đúc kết những gì học được. **Ưu tiên feedback của BA trước:** nếu có vòng `REVISION` nào đã xảy ra, đảm bảo điều BA sửa đã có draft (thường đã tạo ngay lúc REVISION ở trên — kiểm tra lại, đừng bỏ sót). Sau đó mới thêm những gì mới khác: business rule mới confirm, thuật ngữ cần làm rõ, quyết định đặc tả và lý do. Tạo **draft local** cho từng candidate (chưa cần duyệt — `_pending/` chỉ ở local, xem `docs/internal/Memory-Architecture-v1.0.md`):
+Sau khi Gate 4 APPROVED, đúc kết những gì học được. **Ưu tiên feedback của BA trước:** nếu có vòng `REVISION` nào đã xảy ra, đảm bảo điều BA sửa đã có draft (thường đã tạo ngay lúc REVISION ở trên — kiểm tra lại, đừng bỏ sót). Sau đó mới thêm những gì mới khác: business rule mới confirm, thuật ngữ cần làm rõ, quyết định đặc tả và lý do. Tạo **draft local** cho từng candidate (chưa cần duyệt — `_pending/` chỉ ở local, xem `docs/common/Memory-Architecture-v1.0.md`):
 
 ```
 ak memory draft --category 00.Shared/domain --function-id [functionId] \

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

@@ -487,7 +487,7 @@ Trước khi ghi bất kỳ file nào vào `03.Testing/`, đảm bảo AK-Docs
 
 #### Bước 7.5: Retrospect + đề xuất memory draft
 
-Sau khi Gate 4 APPROVED, đúc kết những gì học được. **Ưu tiên trước:** nếu review ở Bước 7 từng phát hiện Major/Critical issue phải sửa lại, đó là bài học giá trị nhất — đảm bảo có draft cho đúng issue đó. Sau đó mới thêm lỗi/bẫy môi trường gặp khi test, business rule cần làm rõ thêm. Tạo **draft local** cho từng candidate (chưa cần duyệt — `_pending/` chỉ ở local, xem `docs/internal/Memory-Architecture-v1.0.md`):
+Sau khi Gate 4 APPROVED, đúc kết những gì học được. **Ưu tiên trước:** nếu review ở Bước 7 từng phát hiện Major/Critical issue phải sửa lại, đó là bài học giá trị nhất — đảm bảo có draft cho đúng issue đó. Sau đó mới thêm lỗi/bẫy môi trường gặp khi test, business rule cần làm rõ thêm. Tạo **draft local** cho từng candidate (chưa cần duyệt — `_pending/` chỉ ở local, xem `docs/common/Memory-Architecture-v1.0.md`):
 
 ```
 ak memory draft --category 01.Lessons/qa --function-id [functionId] \

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

@@ -655,7 +655,7 @@ Bugs logged: [N] | Skipped: [N]
    - **Markdown:** Save to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` (or the custom path/format noted in the requirement doc — e.g. Excel; still write a short pointer + summary into this file so the AK-Docs history stays complete)
 4. Self-review: verify content completeness against the approved requirement outline
 5. Create `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md` with a brief summary of what was generated
-5.5. **Retrospect + propose memory drafts:** synthesize anything genuinely new learned while producing this document (architecture fact, business rule, decision) and create a **local draft** for each (no approval needed yet — `_pending/` is local-only, see `docs/internal/Memory-Architecture-v1.0.md`):
+5.5. **Retrospect + propose memory drafts:** synthesize anything genuinely new learned while producing this document (architecture fact, business rule, decision) and create a **local draft** for each (no approval needed yet — `_pending/` is local-only, see `docs/common/Memory-Architecture-v1.0.md`):
    ```
    ak memory draft --category 00.Shared/architecture --function-id [functionId] \
      --slug <short-kebab-slug> --content "<≤150 words, 1 fact>" \

package/custom/templates/tools/claude.md

@@ -11,3 +11,7 @@ If Gate 1 does not auto-start, wait for the developer to type **"start"**, **"Ga
 - **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".
+
+## 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** auto-start Gate 1. Instead follow `.claude/skills/aiflow-help/SKILL.md`.

package/custom/templates/tools/cursor.md

@@ -10,3 +10,7 @@ If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gat
 - **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".
+
+## 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** auto-start Gate 1. Instead follow `.claude/skills/aiflow-help/SKILL.md`.

package/custom/templates/tools/gemini.md

@@ -12,6 +12,10 @@ If no instructions are automatically followed, wait for the developer to type **
 - **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 `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
 
+## 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** wait for "start"/"Gate 1". Instead follow `.claude/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:

package/docs/common/BA-Specs-Structure.md

@@ -0,0 +1,86 @@
+# BA-Specs — Folder Structure
+
+> **Managed by:** BA  
+> **Organized by:** Output Type → Function-ID → Version  
+> **Naming:** Function-ID format `F-001_User-Login`  
+> **Note:** Templates are managed in a separate shared repo.
+
+---
+
+## Folder Tree
+
+```
+02.BA-Specs/
+│
+├── 00.Requirements/                    # Requirements Gathering
+│   └── F-001_User-Login/
+│       ├── Raw-Requirements_v1.md      # Raw input: ticket, meeting note, email
+│       └── assets/                     # Images, attachments, recordings
+│
+├── 01.Analysis/                        # Gate 1: Business Analysis
+│   └── F-001_User-Login/
+│       ├── Analysis_v1.md              # Current version
+│       └── Analysis_v2.md              # Updated when requirements change
+│
+├── 02.QnA/                             # Gate 2: Q&A nội bộ với stakeholder
+│   └── F-001_User-Login/
+│       └── QnA-Log_v1.md               # Q&A loop until all Confirmed
+│
+├── 03.UI-Prototypes/                   # Gate 3: UI/UX Design
+│   └── F-001_User-Login/
+│       └── UI-Prototype_v1.html        # Static HTML/CSS prototype
+│
+└── 04.UC-Specs/                        # Gate 4: Final UC Specification
+    └── F-001_User-Login/
+        ├── UC-Spec_v2.md               # Current version (BA sign-off)
+        └── _archive/
+            └── UC-Spec_v1.md           # Previous versions
+```
+
+---
+
+## File Naming Convention
+
+| Element | Convention | Example |
+|---|---|---|
+| Section folder | `{N}.{Pascal-Case}/` | `00.Requirements/`, `03.UI-Prototypes/` |
+| Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
+| Requirements file | `Raw-Requirements_v{N}.md` | `Raw-Requirements_v1.md` |
+| Analysis file | `Analysis_v{N}.md` | `Analysis_v2.md` |
+| QnA file | `QnA-Log_v{N}.md` | `QnA-Log_v1.md` |
+| Prototype file | `UI-Prototype_v{N}.html` | `UI-Prototype_v1.html` |
+| Spec file | `UC-Spec_v{N}.md` | `UC-Spec_v2.md` |
+| Archive folder | `_archive/` | `04.UC-Specs/F-001-User-Login/_archive/` |
+
+---
+
+## Gate → Folder Mapping
+
+| Gate | Output | Folder |
+|---|---|---|
+| Gate 1 | Phân tích sơ bộ + Q&A clarify | `00.Requirements/` + `01.Analysis/` |
+| Gate 2 | Q&A loop → Confirmed | `02.QnA/` |
+| Gate 3 | UI Prototype | `03.UI-Prototypes/` |
+| Gate 4 | UC Spec hoàn chỉnh (BA ký off) | `04.UC-Specs/` |
+
+---
+
+## Function-List.md Template
+
+```markdown
+| F-ID  | Feature Name | BA     | Status      | Tickets            | Link Spec |
+|-------|-------------|--------|-------------|-------------------|-----------|
+| F-001 | User Login  | AnhNH  | Done        | #100, #145, #167  | [link]()  |
+| F-002 | Dashboard   | LyLT   | In Progress | #110, #178        | [link]()  |
+| F-003 | ...         | ...    | Not Started | -                 | -         |
+```
+
+---
+
+## Rules
+
+- Không tự sửa template — template nằm trong shared repo riêng
+- Lưu tài liệu lên GitLab **sau khi Gate 4 được APPROVED**
+- Thông báo cho Dev + Tester sau khi UC Spec sẵn sàng
+- Không xóa file cũ — move vào `_archive/` khi có version mới
+- `02.QnA/` là Q&A nội bộ với stakeholder — khác với `01.QnA/` ngoài dự án (dành cho khách hàng)

package/docs/common/CHANGELOG.md

@@ -7,12 +7,13 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [Unreleased]
-
 ## [0.1.7] - 2026-07-20
 
 ### Added
 
+- **`/ak-ask "<question>"` slash command** — new `.claude/commands/ak-ask.md`, installed alongside `/create-spec`, `/create-testcase`, and `/coding` (via `scripts/init.js`'s `setupClaudeCommands`, also refreshed by `ak update`). Explicit, unambiguous trigger for the `aiflow-help` self-help skill: whatever follows `/ak-ask` is treated as a question about ai-flow-kit itself (install, roles, folder structure, CLI, memory workflow), not the developer's active ticket — no `AKQ:` prefix or keyword match needed. Reuses the same doc lookup as `aiflow-help`/`ak ask`: reads `docs/common/INDEX.md`, cites the file it answered from, and says plainly when a topic isn't documented instead of guessing.
+- **`Docs-Management-Flow.md` promoted from `docs/internal/` to `docs/common/`** — the `AK-Docs`/`Shared-Docs` branch + Merge Request workflow doc (who can merge to `main`, which steps are self-review vs. PM-review) now ships to every project too, cross-linked from `INDEX.md`. Its own header still says `Trạng thái: Draft — chờ PM review`, so `ak-ask`/`aiflow-help` should flag that status rather than presenting it as finalized policy. Repointed `bin/aiflow.js`'s `docs` command and `scripts/docs-branch.js` from `docs/internal/...` to `docs/common/...`.
+- **`Project-Structure.md`, `BA-Specs-Structure.md`, `Coding-Structure.md`, `Testing-Structure.md`, and `Memory-Architecture-v1.0.md` promoted from `docs/internal/` to `docs/common/`** — these now ship to every project (`.aiflow/docs/`, via `copyDocsToProject`) instead of staying npm-package-only, so `aiflow-help`/`ak ask`/`/ak-ask` can actually answer the "full `AK-Docs/` folder-structure reference" question that `docs/common/INDEX.md` previously listed as undocumented. `INDEX.md` gained a topic-map row for each file; all in-repo references (`README.md`, `custom/rules/project-conventions.md`, the DEV/BA/QA gate workflow templates, `review-plan`, the memory CLI/hook source comments, the `99.Memory/MEMORY.md` skeleton) were repointed from `docs/internal/...` to `docs/common/...`. `Memory-Architecture-v1.0.md` is a v1.1 architecture doc describing 4 operating flows end-to-end — only Phase 1 (`ak memory draft/list/submit/remove`) is actually implemented; the rest is roadmap, not shipped behavior, so `ak-ask`/`aiflow-help` must say so rather than imply the full doc is live. Historical release notes (`docs/internal/releases/`) and past changelog entries still say `docs/internal/...` and were intentionally left as-is (accurate at time of writing).
 - **`99.Memory/` Project Brain — Phase 1** (`docs/internal/Memory-Architecture-v1.0.md`, v1.1). A git-based, human-approved team knowledge base living inside `AK-Docs/99.Memory/`, replacing the legacy `.aiflow/memory/` JSON store whose only "auto-load" function was dead code no hook ever called. AI now accumulates lessons/facts/decisions across tasks, scored and recalled automatically at session start.
   - **`scripts/memory-store.js`** — new engine: `99.Memory/` skeleton bootstrap; `mem-<functionId>-<slug>` id scheme with folder-per-functionId layout (`_global/` for cross-project facts, flat for `glossary`/`decisions`); hand-rolled frontmatter parse/serialize (no new YAML dependency); dedup-aware draft creation (a repeated slug in the same folder surfaces as a conflict instead of silently duplicating); the §5.2 scoring formula (folder/workflow/tag match, confidence, staleness decay, pending penalty); the Layer-2 relevant-set loader (top-N within a token budget); a local hit-count ledger. Deliberately **dependency-free** (no `fs-extra`/`chalk`) — this file is copied standalone into `.claude/lib/memory-store.js` in every project so the session-start hook can `require()` it without the kit's own `node_modules`.
   - **`scripts/memory.js`** — full rewrite: `ak memory draft|list|submit|remove`, replacing the old `save/get/list/search/delete/clear`. `submit`/`remove` reuse `scripts/docs-branch.js`'s existing branch-then-MR mechanism — same "AI drafts, human approves via Merge Request" model already used by `ak docs branch`/`ak docs submit`.

package/docs/common/Coding-Structure.md

@@ -0,0 +1,179 @@
+# Coding — Folder Structure
+
+> **Managed by:** Dev  
+> **Organized by:** Output Type → Function-ID → Ticket-ID  
+> **Naming:** Function-ID `F-001_User-Login`, file by `TICKET-ID.md`  
+> **Location:** `AK-Docs/04.Coding/` — tách khỏi source repo  
+> **Note:** Templates are managed in a separate shared repo.
+
+---
+
+## Folder Tree
+
+```
+04.Coding/
+│
+├── 00.Overview/
+│   └── _Index.md                           # Tracker: F-ID | Ticket | Dev | Gate | PR
+│
+├── 01.Requirements/                        # Gate 1: AI phân tích ticket + source code
+│   └── F-001_User-Login/
+│       ├── TICKET-100.md                   # Initial implementation
+│       └── TICKET-145.md                   # Enhancement (remember me)
+│
+├── 02.Plans/                               # Gate 2: TDD implementation plan chi tiết
+│   └── F-001_User-Login/
+│       ├── TICKET-100.md
+│       └── TICKET-145.md
+│
+├── 03.TDD-Notes/                           # Gate 3: Test list viết trước + implementation notes
+│   └── F-001_User-Login/
+│       ├── TICKET-100.md
+│       └── TICKET-145.md
+│
+├── 04.Reviews/                             # Gate 4: Self-review + impact analysis
+│   └── F-001_User-Login/
+│       ├── TICKET-100.md
+│       └── TICKET-145.md
+│
+└── 05.Pull-Requests/                       # Gate 5: PR content + review checklist
+    └── F-001_User-Login/
+        ├── TICKET-100.md
+        └── TICKET-145.md
+```
+
+---
+
+## File Naming Convention
+
+| Element | Convention | Example |
+|---|---|---|
+| Section folder | `{N}.{Pascal-Case}/` | `01.Requirements/`, `03.TDD-Notes/` |
+| Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
+| Document file | `TICKET-{ID}.md` | `TICKET-100.md` |
+
+---
+
+## Gate → Folder Mapping
+
+| Gate | Output | Folder |
+|---|---|---|
+| Gate 1 | Requirement analysis + source code analysis + proposed solution | `01.Requirements/F-001/TICKET-100.md` |
+| Gate 2 | TDD implementation plan: step-by-step, file list, test-first | `02.Plans/F-001/TICKET-100.md` |
+| Gate 3 | Test list (written before code) + notes during implementation | `03.TDD-Notes/F-001/TICKET-100.md` |
+| Gate 4 | Self-review: test results, impact analysis, review checklist | `04.Reviews/F-001/TICKET-100.md` |
+| Gate 5 | PR description + reviewer checklist + related doc links | `05.Pull-Requests/F-001/TICKET-100.md` |
+
+---
+
+## File Content Templates
+
+### `01.Requirements` — TICKET-100.md
+```markdown
+## Ticket Summary
+[title, description, AC từ Backlog/Jira]
+
+## Source Code Analysis
+- Files liên quan:
+- Luồng hiện tại:
+- Điểm cần thay đổi:
+
+## Proposed Solution
+- Hướng tiếp cận:
+- Rủi ro:
+
+## Estimate
+- Effort: X giờ
+- Scope ảnh hưởng: [low / medium / high]
+```
+
+### `02.Plans` — TICKET-100.md
+```markdown
+## TDD Implementation Plan
+
+### Step 1: Viết test cho [case A]
+- File: tests/unit/service/UserServiceTest.java
+- Test method: `create_shouldThrow_whenEmailDuplicated()`
+
+### Step 2: Implement [logic A]
+- File: src/service/impl/UserServiceImpl.java
+- Thay đổi: ...
+```
+
+### `03.TDD-Notes` — TICKET-100.md
+```markdown
+## Test List (viết trước khi implement)
+- [ ] TC-01: happy path — tạo user thành công
+- [ ] TC-02: email trùng → throw DuplicateEmailException
+- [ ] TC-03: input null → throw ValidationException
+
+## Implementation Notes
+[ghi chú phát sinh trong quá trình code]
+```
+
+### `04.Reviews` — TICKET-100.md
+```markdown
+## Test Results
+- Unit tests: 12/12 PASS
+- Integration tests: 3/3 PASS
+
+## Impact Analysis
+- Files thay đổi: 5 files
+- Chức năng ảnh hưởng: [danh sách]
+- Breaking changes: Không / Có → [mô tả]
+
+## Review Checklist
+- [ ] Không có business logic trong Controller
+- [ ] Dùng DTO, không expose Entity trực tiếp
+- [ ] @Transactional đúng chỗ (Service, không phải Controller)
+- [ ] Custom exception, không dùng RuntimeException chung
+- [ ] Không log sensitive data
+- [ ] Unit test + Integration test đều pass
+```
+
+### `05.Pull-Requests` — TICKET-100.md
+```markdown
+## PR: [TICKET-100] Tên feature
+
+### Ticket
+[link Backlog/Jira]
+
+### Changes
+- [danh sách thay đổi chính]
+
+### Related Docs
+- UC Spec: [link 02.BA-Specs/04.UC-Specs/F-001_User-Login/]
+- Test Case: [link 03.Testing/01.Testcases/F-001_User-Login/]
+- Dev Plan: [link 04.Coding/02.Plans/F-001_User-Login/TICKET-100.md]
+
+### How to Test
+1. ...
+
+### Checklist for Reviewer
+- [ ] Logic đúng với UC Spec
+- [ ] Test coverage đủ
+- [ ] Không có code smell
+- [ ] Migration (nếu có) an toàn
+```
+
+---
+
+## `_Index.md` — Tracker cho TechLead / PM
+
+```markdown
+| F-ID  | Ticket      | Feature Name | Dev     | Gate              | PR   |
+|-------|------------|-------------|---------|-------------------|------|
+| F-001 | TICKET-100 | User Login  | KhanhNV | ✅✅✅✅⬜ Gate 4   | -    |
+| F-001 | TICKET-145 | Remember Me | AnhNH   | ✅✅✅✅✅ Done     | #42  |
+| F-002 | TICKET-110 | Dashboard   | LyLT    | ✅✅⬜⬜⬜ Gate 2   | -    |
+```
+
+---
+
+## Rules
+
+- Không tự sửa template — template nằm trong shared repo riêng
+- Không code trước Gate 2 được APPROVED
+- Gate 3 bắt buộc TDD: viết test trước → implement → test PASS
+- Lưu tài liệu lên GitLab **trước khi tạo Pull Request**
+- PR description phải đính kèm link: UC Spec + Test Case + Dev Plan