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

package/bin/aiflow.js

@@ -85,12 +85,10 @@ program
             let sub = sec;
             if (sec && !sec.startsWith('-')) {
                 const memAliases = {
-                    's': 'save',
-                    'g': 'get',
+                    'd': 'draft',
                     'ls': 'list',
-                    'sr': 'search',
-                    'd': 'delete',
-                    'cl': 'clear'
+                    'sb': 'submit',
+                    'rm': 'remove',
                 };
                 if (memAliases[sec]) sub = memAliases[sec];
                 cmd = `memory.${sub}`;
@@ -351,45 +349,51 @@ program
         });
     });
 
-// ── memory ────────────────────────────────────────────────────
-// Sub-commands to avoid the ambiguous "memory <action> --save key" pattern
-const memCmd = program.command('memory').alias('mem').description('Manage team knowledge and memory');
-
-memCmd
-    .command('save <key> <value>')
-    .alias('s')
-    .description('Save a memory entry')
-    .action((key, value) => { memoryCommand('save', { key, value }); });
+// ── memory (99.Memory/ Project Brain — see docs/internal/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)');
 
 memCmd
-    .command('get <key>')
-    .alias('g')
-    .description('Retrieve a memory entry')
-    .action((key) => { memoryCommand('get', { key }); });
+    .command('draft')
+    .alias('d')
+    .description('Create a local memory draft in _pending/ (not yet shared with the team)')
+    .requiredOption('-c, --category <category>', 'e.g. 00.Shared/architecture, 01.Lessons/dev, 02.Instincts/approved')
+    .requiredOption('-s, --slug <slug>', 'short kebab-case name, e.g. prevent-429-error')
+    .requiredOption('--content <text>', 'memory body (≤150 words, 1 fact)')
+    .option('-f, --function-id <id>', 'functionId this memory is scoped to (omit/= global for cross-project facts)')
+    .option('--scope <scope>', 'alternative to --function-id for flat categories (glossary/decisions)')
+    .option('-t, --tags <list>', 'comma-separated tags, scorer matches on these')
+    .option('-w, --workflows <list>', 'comma-separated workflows (coding, create-spec, create-testcase, gen-doc, all)')
+    .option('--source <text>', 'trace: ticket / Gate this was learned from')
+    .option('--confidence <n>', 'AI self-rated 0.3–0.7', '0.5')
+    .action((options) => { memoryCommand('draft', options); });
 
 memCmd
     .command('list')
     .alias('ls')
-    .description('List all memories')
-    .action(() => { memoryCommand('list'); });
-
-memCmd
-    .command('search <query>')
-    .alias('sr')
-    .description('Search memories by keyword')
-    .action((query) => { memoryCommand('search', { query }); });
+    .option('-a, --approved', 'list approved memories instead of local pending drafts')
+    .action((options) => { memoryCommand('list', options); });
 
 memCmd
-    .command('delete <key>')
-    .alias('d')
-    .description('Delete a memory entry')
-    .action((key) => { memoryCommand('delete', { key }); });
+    .command('submit <path>')
+    .alias('sb')
+    .description('Move a pending draft (path from `ak memory list`) to its destination and open a Merge Request')
+    .requiredOption('-t, --title <title>', 'commit message / MR title')
+    .option('-d, --description <text>', 'MR description', '')
+    .option('-y, --yes', 'skip the interactive confirm — only pass this after the user has approved in chat')
+    .action((path, options) => { memoryCommand('submit', { ...options, _positional: [path] }); });
 
 memCmd
-    .command('clear')
-    .alias('cl')
-    .description('Clear all memories')
-    .action(() => { memoryCommand('clear'); });
+    .command('remove <path>')
+    .alias('rm')
+    .description('Propose removing an approved memory (path from `ak memory list --approved`)')
+    .requiredOption('-t, --title <title>', 'commit message / MR title')
+    .option('-d, --description <text>', 'MR description', '')
+    .option('--reason <text>', 'why this memory is being removed')
+    .option('--hard', 'delete outright instead of moving to _deprecated/ (rarely — see doc §Luồng 4)')
+    .option('-y, --yes', 'skip the interactive confirm — only pass this after the user has approved in chat')
+    .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`;

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

@@ -164,6 +164,22 @@ Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 - [ ] UI matches `design-context.md` (layout, color, typography, spacing) — UI tickets only
 ```
 
+### 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`):
+
+```
+ak memory draft --category 01.Lessons/dev --function-id [functionId] \
+  --slug <short-kebab-slug> --content "<≤150 từ, 1 fact>" \
+  --tags <tag1,tag2> --workflows coding --source "[ticket-id] / Gate 4"
+```
+
+Other useful categories here: `00.Shared/architecture` (facts about the system discovered while coding), `00.Shared/decisions` (a technical choice made and why). Skip this step if nothing genuinely new was learned — don't manufacture a memory just to have one.
+
+If `ak memory draft` reports a conflict (a similar memory already exists), don't create a duplicate — mention it to the developer instead so they can decide whether to edit the existing one.
+
+List the created draft(s) in the Step 3 message below so the developer knows what's sitting in `_pending/` — they (or anyone on the team) can inspect and `ak memory submit` it later when ready to share with the team.
+
 ### Step 3: GATE 4 — Present to Developer
 
 ```markdown
@@ -177,6 +193,7 @@ Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 - 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:**
 1. Review the summary above
@@ -199,10 +216,12 @@ Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 → Guide on creating a Pull Request
 
 **If the developer types "BUG: [description]" — coding bug:**
+→ **Immediately draft a memory** capturing exactly what the developer flagged and why it was wrong (`ak memory draft --category 01.Lessons/dev --function-id [functionId] --slug <slug> --content "<the bug + the fix>" --workflows coding --source "[ticket-id] / Gate 4 dev feedback"`) — do this before fixing, while the correction is fresh; don't wait for Step 2.5 on the next pass to catch it in hindsight.
 → Analyze bug, fix, rerun verification
 → Repeat from Step 1 of Gate 4
 
 **If the developer types "BUG: [description]" — requirement bug:**
+→ **Immediately draft a memory** (same category/command as above) capturing what was misunderstood about the requirement and what it actually should have been — this is a requirement-comprehension lesson, valuable even though Gate 1 itself has no retrospect step of its own.
 → Notify: "This is a requirement bug, requirement document needs update"
 → Return to Gate 1, update requirement.md, wait for APPROVED again
 

package/custom/templates/memory/CODEOWNERS

@@ -0,0 +1,8 @@
+# Áp dụng thủ công vào file CODEOWNERS của repo AK-Docs (mục 5.1.2 Memory-Architecture-v1.0.md).
+# GitLab tự gợi ý các reviewer này làm Consult khi diff đụng đúng thư mục — không phải approver
+# (approver luôn là PM, cấu hình riêng ở MR approval rule, không qua CODEOWNERS).
+
+99.Memory/00.Shared/architecture/ @TL
+99.Memory/00.Shared/domain/       @BA
+99.Memory/00.Shared/glossary/     @BA
+99.Memory/02.Instincts/           @TL

package/custom/templates/memory/ci/memory-finalize.yml

@@ -0,0 +1,9 @@
+# Áp dụng thủ công vào .gitlab-ci.yml của repo AK-Docs (mục 5.1.2 Memory-Architecture-v1.0.md).
+# Chạy khi MR label `memory` đã đủ approval từ PM — flip status, rebuild MEMORY.md, commit lên branch.
+memory-finalize:
+  stage: finalize
+  rules:
+    - if: '$CI_MERGE_REQUEST_LABELS =~ /memory/ && $CI_MERGE_REQUEST_APPROVED == "true"'
+  script:
+    - node scripts/ci/memory-finalize.js  # flip status: approved, điền reviewed_by, rebuild MEMORY.md
+                                            # (script CI thực tế nằm trong repo AK-Docs, không phải kit)

package/custom/templates/memory/ci/memory-lint.yml

@@ -0,0 +1,10 @@
+# Áp dụng thủ công vào .gitlab-ci.yml của repo AK-Docs (mục 5.1.2 Memory-Architecture-v1.0.md).
+# Chạy trên mọi MR có label `memory`, TRƯỚC khi PM approve.
+memory-lint:
+  stage: lint
+  rules:
+    - if: '$CI_MERGE_REQUEST_LABELS =~ /memory/'
+  script:
+    - node scripts/ci/memory-lint.js  # validate frontmatter đủ trường, ≤150 từ, 1 fact/file,
+                                       # id không trùng, id khớp đường dẫn file, quét secret/PII
+                                       # (script CI thực tế nằm trong repo AK-Docs, không phải kit)

package/custom/templates/memory/gitlab/merge_request_templates/memory.md

@@ -0,0 +1,18 @@
+## Memory MR — Ticket: <!-- TICKET-123 -->
+
+**Loại:** Thêm mới / Gỡ bỏ (soft-remove / hard-remove)
+**Mem-id(s):** <!-- mem-F003-refund-flow, mem-F003-prevent-429-error -->
+
+### Checklist PM (bắt buộc trước khi approve)
+
+- [ ] Đúng sự thật và còn hiệu lực?
+- [ ] Trace được nguồn gốc (`source:` trỏ đúng ticket/Gate)?
+- [ ] Nội dung ngắn gọn (≤150 từ), đúng khuôn mẫu 1 file = 1 fact?
+- [ ] Có hành động cụ thể áp dụng được (mục "Áp dụng")?
+- [ ] Phạm vi (`scope:`) hẹp nhất có thể — không lạm dụng `global`?
+- [ ] Không mâu thuẫn với `.rules/`?
+- [ ] Đã tham vấn đúng người cho nội dung nhạy cảm (TL cho kỹ thuật, BA/Comtor cho glossary/domain)?
+
+### Consult (tự động theo CODEOWNERS)
+
+TL/BA được tag tự động theo thư mục bị đụng — đây là góp ý, quyền quyết vẫn ở PM.

package/custom/templates/memory/memory-item.md

@@ -0,0 +1,25 @@
+---
+id: mem-<functionId>-<slug>       # CLI tự sinh từ vị trí file: mem-<functionId>-<slug>
+                                   # slug do AI đặt — ngắn, đọc là hiểu memory lưu gì
+                                   # (vd: basic-payment-flow, refund-flow, prevent-429-error).
+                                   # KHÔNG có timestamp: trùng slug trong cùng folder chính là
+                                   # tín hiệu chống trùng lặp — CLI hỏi "memory tương tự đã có,
+                                   # cập nhật bản cũ thay vì tạo mới?"
+type: lesson | fact | decision | glossary | instinct
+workflows: [coding, create-testcase]  # workflow nào cần recall; [all] nếu mọi workflow
+tags: [payment, refund, http-429]     # ascii-lowercase, AI tự sinh khi tạo draft —
+                                       # scorer CHỈ so khớp trên trường này (không so body — JP/VN)
+scope: F-003_Payment | global     # trùng với folder chứa file; global → file đặt trong _global/
+confidence: 0.6                   # AI tự chấm 0.3–0.7; reviewer chỉnh khi duyệt
+source: TICKET-123 / Gate 4       # trace: học được từ đâu
+status: pending                   # pending | approved | deprecated
+hits: 0                           # consolidate cập nhật từ telemetry local — không sửa tay
+created: 2026-07-09
+reviewed_by:                      # điền khi approve
+refs: []                          # (tùy chọn) file/dir code hoặc docs mà memory phụ thuộc
+verified_commit:                  # commit đã verify refs lần cuối (CLI tự điền)
+stale: false                      # hook tự set true khi refs thay đổi sau verified_commit
+---
+<Nội dung: TỐI ĐA 150 từ, 1 file = 1 fact duy nhất.>
+
+**Áp dụng:** <hành động cụ thể AI/người cần làm khi gặp tình huống này.>

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

@@ -0,0 +1,7 @@
+# 99.Memory — Project Brain Index
+
+> Auto-generated by `ak memory submit` / `ak memory remove` when a Merge Request is merged into `main`.
+> **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.

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

@@ -429,7 +429,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 → Nếu blocked: làm theo gate-review skill response protocol
 
 **Phản hồi đặc biệt:**
-- BA gõ `REVISION: [nội dung]` → cập nhật section liên quan → re-generate review file → hiển thị lại gate pause
+- BA gõ `REVISION: [nội dung]` → **trước khi sửa**, tạo ngay 1 memory draft ghi lại chính xác điều BA vừa chỉnh (`ak memory draft --category 01.Lessons/ba --function-id [functionId] --slug <slug> --content "<điều BA sửa + vì sao>" --workflows create-spec --source "[functionId] / Gate 4 BA feedback"`) — đây là tín hiệu giá trị nhất, đừng chờ Bước 7.5 mới bắt lại theo trí nhớ → cập nhật section liên quan → re-generate review file → hiển thị lại gate pause
 
 **Definition of Done:**
 - [ ] File `UC-Spec_v1.md` đúng vị trí và cấu trúc template
@@ -441,6 +441,18 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 > **Telemetry:** Run `ak gate 4 start --ticket [functionId]` khi bắt đầu gate này.
 > Run `ak gate 4 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.
 
+#### 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`):
+
+```
+ak memory draft --category 00.Shared/domain --function-id [functionId] \
+  --slug <slug-ngắn> --content "<≤150 từ, 1 fact>" \
+  --tags <tag1,tag2> --workflows create-spec --source "[functionId] / Gate 4"
+```
+
+Category khác hữu ích ở đây: `00.Shared/glossary` (thuật ngữ JP↔VN↔EN mới xác nhận — flat, không cần `--function-id`), `01.Lessons/ba` (bài học khi làm spec), `00.Shared/decisions` (quyết định đặc tả). Bỏ qua bước này nếu không có gì thực sự mới. Nếu `ak memory draft` báo trùng, đừng tạo bản mới — báo cho BA để họ quyết định sửa bản cũ.
+
 #### Bước 8: Submit AK-Docs lên remote qua Merge Request
 
 Sau khi Gate 4 đã APPROVED (UC Spec hoàn thành):

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

@@ -485,6 +485,18 @@ Trước khi ghi bất kỳ file nào vào `03.Testing/`, đảm bảo AK-Docs
 > **Telemetry:** Run `ak gate 4 start --ticket [functionId]` khi bắt đầu gate này.
 > Run `ak gate 4 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.
 
+#### 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`):
+
+```
+ak memory draft --category 01.Lessons/qa --function-id [functionId] \
+  --slug <slug-ngắn> --content "<≤150 từ, 1 fact>" \
+  --tags <tag1,tag2> --workflows create-testcase --source "[functionId] / Gate 4"
+```
+
+Category khác hữu ích ở đây: `00.Shared/domain` (business rule phát hiện khi thiết kế test), `00.Shared/glossary` (thuật ngữ — flat, không cần `--function-id`). Bỏ qua bước này nếu không có gì thực sự mới. Nếu `ak memory draft` báo trùng, đừng tạo bản mới — báo cho QA để họ quyết định sửa bản cũ.
+
 #### Bước 8: Submit AK-Docs lên remote qua Merge Request
 
 Sau khi Gate 4 đã APPROVED (bộ Test Case hoàn thành):

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

@@ -655,6 +655,13 @@ 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`):
+   ```
+   ak memory draft --category 00.Shared/architecture --function-id [functionId] \
+     --slug <short-kebab-slug> --content "<≤150 words, 1 fact>" \
+     --tags <tag1,tag2> --workflows gen-doc --source "[ticket-id] / Gate 2"
+   ```
+   Skip if nothing new was learned. If `ak memory draft` reports a conflict, don't duplicate — mention the existing one instead.
 6. **Submit AK-Docs lên remote qua Merge Request:**
    - Soạn title + description cho MR (tóm tắt tài liệu vừa tạo, link ticket gốc), hiển thị cho người dùng xem trước.
    - Hỏi: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?" → đồng ý thì chạy `ak docs submit --title "..." --description "..." --yes`; từ chối thì dừng, để người dùng tự commit/tạo MR khi sẵn sàng.

package/package.json

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

package/scripts/create-score-excel.js

@@ -25,7 +25,7 @@ function norm(cmd) {
 }
 
 // ── Version helpers ─────────────────────────────────────────────────────────
-const CURRENT_VERSION = '0.1.4';
+const CURRENT_VERSION = '0.1.5';
 
 function parseVersion(v) {
   if (!v || v === '-' || v === '' || v.toLowerCase() === 'unknown') return null;

package/scripts/hooks/session-start.js

@@ -9,6 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { execSync } = require('child_process');
 
 function loadTelemetry() {
     try { return require('../telemetry/record'); } catch (_) { }
@@ -29,7 +30,7 @@ let tasksDir = '';
 let raw = '';
 process.stdin.setEncoding('utf-8');
 process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
+process.stdin.on('end', async () => {
     let hookData = {};
     try { hookData = JSON.parse(raw || '{}'); } catch (_) { }
 
@@ -59,9 +60,10 @@ process.stdin.on('end', () => {
 
     // ── 2. Load active ticket context ──────────────────────────────
     let contextBlock = '';
+    let ctx = null;
     try {
         if (fs.existsSync(contextPath)) {
-            const ctx = JSON.parse(fs.readFileSync(contextPath, 'utf-8'));
+            ctx = JSON.parse(fs.readFileSync(contextPath, 'utf-8'));
             if (ctx.taskId && ctx.title) {
                 const taskState = loadTaskState(ctx.taskId);
                 contextBlock = buildContextPrompt(ctx, taskState);
@@ -97,6 +99,34 @@ process.stdin.on('end', () => {
         }
     } catch (_) { }
 
+    // ── 3.5 Load relevant memory (99.Memory/ Project Brain) ────────
+    // See docs/internal/Memory-Architecture-v1.0.md — Luồng 3 (Nạp/Sử dụng).
+    let memoryBlock = '';
+    try {
+        const workspaceRoot = resolveWorkspaceRoot(projectRoot);
+        const akDocsPath = path.join(workspaceRoot, 'AK-Docs');
+        if (fs.existsSync(akDocsPath)) {
+            if (fs.existsSync(path.join(akDocsPath, '.git'))) {
+                pullAkDocsWithTimeout(akDocsPath);
+            }
+            const memoryStore = require('../lib/memory-store');
+            const functionId = ctx ? (ctx.functionId || ctx.screenId) : null;
+            const workflow = inferWorkflow(ctx);
+            const tags = ctx ? extractQueryTags(ctx) : [];
+
+            const [indexContent, relevant] = await Promise.all([
+                memoryStore.readIndex(workspaceRoot),
+                memoryStore.loadRelevant(workspaceRoot, { functionId, workflow, tags }),
+            ]);
+
+            memoryBlock = buildMemoryBlock(indexContent, relevant);
+            // recordHits' ledger lives under THIS project's own .aiflow/ (projectRoot),
+            // not the workspace root — matches where context/tasks/ already live. Batched
+            // into one read-modify-write (see memory-store.js) instead of one call per id.
+            await memoryStore.recordHits(projectRoot, relevant.map(m => m.id));
+        }
+    } catch (_) { }
+
     // ── 4. Combine and output ──────────────────────────────────────
     const parts = [];
     if (skillContent) {
@@ -105,6 +135,9 @@ process.stdin.on('end', () => {
     if (contextBlock) {
         parts.push(contextBlock);
     }
+    if (memoryBlock) {
+        parts.push(memoryBlock);
+    }
 
     const combined = parts.join('\n\n');
     const escaped = combined
@@ -126,6 +159,76 @@ process.stdin.on('end', () => {
 
 // ── Helpers ────────────────────────────────────────────────────
 
+// AK-Docs lives as a sibling of the project repo at the workspace root (see
+// scripts/docs-repo.js), but this hook can't rely on process.cwd() — Claude Code's
+// hook invocation cwd isn't guaranteed to be the workspace root. Try the project
+// root itself first (project opened standalone with AK-Docs cloned alongside it
+// at that same level), then its parent (the documented sibling-of-the-repo layout).
+function resolveWorkspaceRoot(projectRoot) {
+    if (fs.existsSync(path.join(projectRoot, 'AK-Docs'))) return projectRoot;
+    const parent = path.resolve(projectRoot, '..');
+    if (fs.existsSync(path.join(parent, 'AK-Docs'))) return parent;
+    return projectRoot;
+}
+
+function pullAkDocsWithTimeout(akDocsPath, timeoutMs = 5000) {
+    try {
+        execSync('git pull', { cwd: akDocsPath, stdio: 'ignore', timeout: timeoutMs });
+    } catch (err) {
+        process.stderr.write(`[aiflow] ⚠ Không pull được AK-Docs (${String(err.message || err).split('\n')[0]}) — dùng bản memory hiện có trên máy.\n`);
+    }
+}
+
+// Map the active task's taskType to the workflow profile used by the memory scorer
+// (doc §5.2 profile table). Unresolvable → null, which falls back to the doc's
+// "gen-doc / không xác định" default profile inside memory-store's scoring.
+function inferWorkflow(ctx) {
+    if (!ctx) return null;
+    const t = ctx.taskType;
+    if (t === 'gen-doc') return 'gen-doc';
+    if (t === 'testing') return 'create-testcase';
+    if (t === 'spec') return 'create-spec';
+    if (!t || ['feature', 'bug-fix', 'refactor', 'documentation', 'investigation'].includes(t)) return 'coding';
+    return null;
+}
+
+// Rough query-side tag extraction from the ticket title — the scorer only needs a
+// handful of significant words to overlap against memory `tags:` (doc §5.2 formula).
+function extractQueryTags(ctx) {
+    const text = `${ctx.title || ''} ${ctx.description || ''}`;
+    return [...new Set(
+        text.toLowerCase()
+            .replace(/[^a-z0-9\s-]/g, ' ')
+            .split(/\s+/)
+            .filter(w => w.length > 3)
+    )].slice(0, 8);
+}
+
+function buildMemoryBlock(indexContent, relevant) {
+    if (!indexContent && (!relevant || relevant.length === 0)) return '';
+    const lines = ['<PROJECT_MEMORY>'];
+    lines.push('**99.Memory/ index (Lớp 1 — luôn có; xem MEMORY.md để biết toàn bộ danh mục):**');
+    lines.push('```markdown');
+    lines.push((indexContent || '(chưa có memory nào được approve)').trim());
+    lines.push('```');
+    if (relevant && relevant.length > 0) {
+        lines.push('');
+        lines.push(`**Memory liên quan nhất tới task này (Lớp 2, ${relevant.length} mục):**`);
+        for (const m of relevant) {
+            const pendingTag = m.status === 'pending'
+                ? ' ⚠ CHƯA DUYỆT — chỉ máy này thấy, kiểm tra lại trước khi tin'
+                : '';
+            const firstLine = (m.content || '').trim().split('\n')[0];
+            lines.push(`- **${m.id}** (${m.type}, scope=${m.scope})${pendingTag}`);
+            lines.push(`  ${firstLine}`);
+        }
+    }
+    lines.push('');
+    lines.push('Nếu memory mâu thuẫn với `.rules/`, `.rules/` thắng — báo cho developer biết.');
+    lines.push('</PROJECT_MEMORY>');
+    return lines.join('\n');
+}
+
 function loadTaskState(taskId) {
     try {
         const statePath = path.join(tasksDir, taskId, 'task-state.json');

package/scripts/init.js

@@ -4,6 +4,7 @@ const os = require('os');
 const chalk = require('chalk');
 const { input, checkbox, confirm } = require('@inquirer/prompts');
 const { syncDocsRepos } = require('./docs-repo');
+const memoryStore = require('./memory-store');
 
 const PKG_DIR = path.join(__dirname, '..');
 const GLOBAL_AIFLOW_DIR = path.join(os.homedir(), '.aiflow');
@@ -229,6 +230,16 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
     await fs.copy(telemetrySrc, telemetryDest, { overwrite: true });
     await fs.writeJson(path.join(telemetryDest, 'package.json'), { type: 'commonjs' }, { spaces: 2 });
 
+    // Copy memory-store.js so session-start.js can require('../lib/memory-store') for the
+    // 99.Memory/ Layer 1+2 load — same reason as telemetry above: only the hook file itself
+    // is deployed, not the rest of scripts/. memory-store.js is dependency-free by design
+    // (no fs-extra/chalk — see its own header comment) specifically so it can be copied alone.
+    // Own subdir + nested package.json for the same CJS-pinning reason as hooks/telemetry above.
+    const libDest = path.join(claudeDir, 'lib');
+    await fs.ensureDir(libDest);
+    await fs.copy(path.join(PKG_DIR, 'scripts', 'memory-store.js'), path.join(libDest, 'memory-store.js'), { overwrite: true });
+    await fs.writeJson(path.join(libDest, 'package.json'), { type: 'commonjs' }, { spaces: 2 });
+
     const settingsFile = path.join(claudeDir, 'settings.json');
     let settings = {};
     if (await fs.pathExists(settingsFile)) {
@@ -1079,6 +1090,19 @@ async function init(options) {
         // ── Sync AK-Docs / Shared-Docs sibling repos ──────────────────
         await syncDocsRepos(projectDir);
 
+        // ── Bootstrap 99.Memory/ skeleton (Luồng 1 — Khởi tạo) ────────
+        // Free: no reads, no token cost — just an empty folder skeleton if AK-Docs
+        // exists and doesn't have one yet (docs/internal/Memory-Architecture-v1.0.md §4).
+        const memorySkeleton = await memoryStore.ensureSkeleton(projectDir);
+        if (memorySkeleton.created) {
+            console.log(chalk.green('✓ Đã tạo khung 99.Memory/ trong AK-Docs (chưa có ghi nhớ nào).'));
+            const gitignoreResult = await memoryStore.ensureMemoryGitignored(projectDir);
+            if (memorySkeleton.committed || gitignoreResult.committed) {
+                console.log(chalk.yellow('  ⚠ Đã commit local trên nhánh hiện tại của AK-Docs — `main` là protected branch,'));
+                console.log(chalk.yellow('    hãy tự `git push` khi sẵn sàng (không tự động push).'));
+            }
+        }
+
         // ── Auto-detect or prompt for framework if not supplied ──────
         if (frameworks.length === 0) {
             const stateFilePath = path.join(aiflowDir, 'state.json');