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

package/scripts/docs-branch.js

@@ -0,0 +1,264 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+const { confirm } = require('@inquirer/prompts');
+const { resolveDocsRepoPath, DOC_REPOS } = require('./docs-repo');
+
+// Implements the branch + Merge Request half of docs/internal/Docs-Management-Flow.md:
+// PM reviews & merges into `main`; every other role updates docs on a
+// `feature/<functionId>/<taskId>` branch created from `main`, then submits a MR.
+//
+// Safety model (mirrors the rest of the kit's "AI drafts — human approves" rule,
+// see scripts/hooks/block-git-write.js): AI must never call these with --yes until
+// the developer has explicitly approved the plan in chat. Without --yes and without
+// an interactive TTY, both commands only print the plan and make no changes.
+
+const PROJECT_DIR = process.cwd();
+
+function sh(cmd, cwd) {
+    return execSync(cmd, { cwd, encoding: 'utf-8' }).trim();
+}
+
+// Same as sh(), but swallows stderr — for existence checks expected to fail often/normally.
+function shQuiet(cmd, cwd) {
+    return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+function isKnownRepoName(name) {
+    return DOC_REPOS.some((r) => r.name === name);
+}
+
+function resolveRepo(repoName) {
+    if (!isKnownRepoName(repoName)) {
+        console.log(chalk.red(`✗ Repo không hợp lệ: "${repoName}". Chỉ chấp nhận: ${DOC_REPOS.map((r) => r.name).join(', ')}`));
+        return null;
+    }
+    const repoPath = resolveDocsRepoPath(PROJECT_DIR, repoName);
+    if (!fs.pathExistsSync(repoPath) || !fs.pathExistsSync(path.join(repoPath, '.git'))) {
+        console.log(chalk.red(`✗ ${repoName}/ không tồn tại hoặc không phải git repo tại ${repoPath}.`));
+        console.log(chalk.gray(`  Hãy clone repo này vào thư mục root trước.`));
+        return null;
+    }
+    return repoPath;
+}
+
+function branchName(functionId, taskId) {
+    return `feature/${functionId}/${taskId}`;
+}
+
+function currentBranch(repoPath) {
+    return sh('git rev-parse --abbrev-ref HEAD', repoPath);
+}
+
+function hasUncommittedChanges(repoPath) {
+    return sh('git status --porcelain', repoPath).length > 0;
+}
+
+function localBranchExists(repoPath, name) {
+    try {
+        shQuiet(`git rev-parse --verify refs/heads/${name}`, repoPath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function remoteBranchExists(repoPath, name) {
+    try {
+        return shQuiet(`git ls-remote --heads origin ${name}`, repoPath).length > 0;
+    } catch {
+        return false;
+    }
+}
+
+// Prints the plan and gates on explicit approval — either an interactive "y"
+// (developer running the command directly) or a pre-confirmed --yes flag
+// (AI, only after the developer approved the same plan in chat).
+async function ensureApproval(planLines, opts) {
+    console.log(chalk.yellow('\n📋 Kế hoạch thực hiện:'));
+    planLines.forEach((l) => console.log(chalk.gray(`  • ${l}`)));
+
+    if (opts.yes) return true;
+
+    if (!process.stdin.isTTY) {
+        console.log(chalk.red('\n✗ Cần xác nhận trước khi thực hiện.'));
+        console.log(chalk.gray('  AI: hỏi user đồng ý trong chat trước, rồi chạy lại lệnh này kèm --yes.'));
+        console.log(chalk.gray('  Người dùng: chạy lại lệnh này trong terminal để được hỏi xác nhận trực tiếp.'));
+        return false;
+    }
+
+    return confirm({ message: '\nTiếp tục thực hiện các bước trên?', default: false });
+}
+
+async function createBranch(options) {
+    const repoName = options.repo || 'AK-Docs';
+    const repoPath = resolveRepo(repoName);
+    if (!repoPath) { process.exitCode = 1; return null; }
+
+    if (!options.functionId || !options.taskId) {
+        console.log(chalk.red('✗ Cần cả --function-id và --task-id (hoặc tham số vị trí <functionId> <taskId>).'));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const base = options.base || 'main';
+    const branch = branchName(options.functionId, options.taskId);
+
+    if (localBranchExists(repoPath, branch)) {
+        console.log(chalk.green(`✓ Branch ${branch} đã tồn tại trong ${repoName} — checkout.`));
+        execSync(`git checkout ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+        return { repoPath, repoName, branch, created: false };
+    }
+
+    if (hasUncommittedChanges(repoPath)) {
+        console.log(chalk.red(`✗ ${repoName} đang có thay đổi chưa commit — xử lý (commit/stash) trước khi tạo branch mới.`));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const ok = await ensureApproval([
+        `Repo: ${repoName}`,
+        `git checkout ${base} && git pull origin ${base} --ff-only`,
+        `git checkout -b ${branch}`,
+        `git push -u origin ${branch}`,
+    ], options);
+    if (!ok) { process.exitCode = 1; return null; }
+
+    try {
+        console.log(chalk.cyan(`\n⟳ Cập nhật ${base} mới nhất...`));
+        execSync(`git checkout ${base}`, { cwd: repoPath, stdio: 'inherit' });
+        execSync(`git pull origin ${base} --ff-only`, { cwd: repoPath, stdio: 'inherit' });
+
+        console.log(chalk.cyan(`⟳ Tạo branch ${branch}...`));
+        execSync(`git checkout -b ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+        execSync(`git push -u origin ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+
+        console.log(chalk.green(`\n✓ Đã tạo và đẩy branch ${branch} từ ${base} (repo ${repoName}).`));
+        return { repoPath, repoName, branch, created: true };
+    } catch (err) {
+        console.log(chalk.red(`\n✗ Lỗi khi tạo branch: ${err.message}`));
+        process.exitCode = 1;
+        return null;
+    }
+}
+
+function detectProvider(repoPath) {
+    let remoteUrl = '';
+    try { remoteUrl = sh('git remote get-url origin', repoPath); } catch { /* no remote */ }
+    if (/gitlab/i.test(remoteUrl)) return { provider: 'gitlab', remoteUrl };
+    if (/github/i.test(remoteUrl)) return { provider: 'github', remoteUrl };
+    return { provider: 'unknown', remoteUrl };
+}
+
+function hasCli(bin) {
+    try {
+        execSync(`${bin} --version`, { stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function webUrlFromRemote(remoteUrl) {
+    const sshMatch = remoteUrl.match(/^git@([^:]+):(.+?)(\.git)?$/);
+    if (sshMatch) return `https://${sshMatch[1]}/${sshMatch[2]}`;
+    return remoteUrl.replace(/\.git$/, '');
+}
+
+function openMergeRequest(repoPath, { branch, base, title, description }) {
+    const { provider, remoteUrl } = detectProvider(repoPath);
+
+    if (provider === 'gitlab' && hasCli('glab')) {
+        execSync(
+            `glab mr create --source-branch "${branch}" --target-branch "${base}" ` +
+            `--title ${JSON.stringify(title)} --description ${JSON.stringify(description || '')} --yes`,
+            { cwd: repoPath, stdio: 'inherit' }
+        );
+        return;
+    }
+    if (provider === 'github' && hasCli('gh')) {
+        execSync(
+            `gh pr create --base "${base}" --head "${branch}" ` +
+            `--title ${JSON.stringify(title)} --body ${JSON.stringify(description || '')}`,
+            { cwd: repoPath, stdio: 'inherit' }
+        );
+        return;
+    }
+
+    if (!remoteUrl) {
+        console.log(chalk.yellow('\n⚠ Không tìm thấy remote "origin" — hãy tự tạo Merge Request thủ công.'));
+        return;
+    }
+
+    const webBase = webUrlFromRemote(remoteUrl);
+    let url;
+    if (provider === 'gitlab') {
+        url = `${webBase}/-/merge_requests/new?merge_request%5Bsource_branch%5D=${encodeURIComponent(branch)}` +
+              `&merge_request%5Btarget_branch%5D=${encodeURIComponent(base)}` +
+              `&merge_request%5Btitle%5D=${encodeURIComponent(title)}`;
+    } else if (provider === 'github') {
+        url = `${webBase}/compare/${encodeURIComponent(base)}...${encodeURIComponent(branch)}?expand=1&title=${encodeURIComponent(title)}`;
+    } else {
+        url = webBase;
+    }
+    console.log(chalk.yellow(`\n⚠ Không tìm thấy 'glab'/'gh' CLI — mở link sau để tạo Merge Request thủ công:`));
+    console.log(chalk.cyan(`  ${url}\n`));
+}
+
+async function submitDocs(options) {
+    const repoName = options.repo || 'AK-Docs';
+    const repoPath = resolveRepo(repoName);
+    if (!repoPath) { process.exitCode = 1; return null; }
+
+    if (!options.title) {
+        console.log(chalk.red('✗ Cần --title (tiêu đề commit / Merge Request).'));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const base = options.base || 'main';
+    const branch = currentBranch(repoPath);
+    if (branch === base) {
+        console.log(chalk.red(`✗ Đang ở nhánh ${base} — tạo branch feature trước bằng "ak docs branch <functionId> <taskId>".`));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const dirty = hasUncommittedChanges(repoPath);
+    if (!dirty && !remoteBranchExists(repoPath, branch)) {
+        console.log(chalk.yellow(`Không có thay đổi để submit và branch ${branch} chưa từng được push.`));
+        process.exitCode = 1;
+        return null;
+    }
+    if (!dirty) {
+        console.log(chalk.yellow('Không có thay đổi mới để commit — sẽ chỉ đảm bảo branch đã push và mở Merge Request.'));
+    }
+
+    const planLines = [`Repo: ${repoName}, branch: ${branch} → ${base}`];
+    if (dirty) planLines.push('git add -A', `git commit -m ${JSON.stringify(options.title)}`);
+    planLines.push(`git push -u origin ${branch}`, `Mở Merge Request: "${options.title}" (${branch} → ${base})`);
+
+    const ok = await ensureApproval(planLines, options);
+    if (!ok) { process.exitCode = 1; return null; }
+
+    try {
+        if (dirty) {
+            execSync('git add -A', { cwd: repoPath, stdio: 'inherit' });
+            execSync(`git commit -m ${JSON.stringify(options.title)}`, { cwd: repoPath, stdio: 'inherit' });
+        }
+        execSync(`git push -u origin ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+
+        console.log(chalk.cyan('\n⟳ Mở Merge Request...'));
+        openMergeRequest(repoPath, { branch, base, title: options.title, description: options.description || '' });
+
+        console.log(chalk.green(`\n✓ Đã submit ${branch} → ${base} (repo ${repoName}). Chờ PM review.`));
+        return { repoPath, repoName, branch };
+    } catch (err) {
+        console.log(chalk.red(`\n✗ Lỗi khi submit: ${err.message}`));
+        process.exitCode = 1;
+        return null;
+    }
+}
+
+module.exports = { createBranch, submitDocs, branchName, currentBranch, hasUncommittedChanges };

package/scripts/hooks/figma-rate-limit.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: throttle mcp__figma__* calls to stay under Figma's Tier-1 REST
+ * budget (10/min on a Starter-plan Full seat). Sleeps instead of blocking, so the
+ * tool call always proceeds — just never faster than the budget allows.
+ *
+ * Budget is counted in "units" ≈ underlying Figma REST calls
+ * (verified against figma-developer-mcp v0.13.2):
+ *   get_figma_data        → 1 unit  (one /v1/files/:key[/nodes] call)
+ *   download_figma_images → 3 units (fills map + PNG render + SVG render, worst case)
+ * Override with FIGMA_RATE_LIMIT_UNITS (default 6/60s — safety margin under 10/min).
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WINDOW = 60; // seconds
+const MAX_UNITS = parseInt(process.env.FIGMA_RATE_LIMIT_UNITS || '6', 10) || 6;
+const STATE = path.join(
+    os.tmpdir(),
+    `figma-mcp-rate-limit-${typeof process.getuid === 'function' ? process.getuid() : 'user'}.log`
+);
+
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(data));
+    });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function readStamps() {
+    try {
+        return fs
+            .readFileSync(STATE, 'utf8')
+            .split('\n')
+            .map((l) => parseInt(l, 10))
+            .filter((n) => Number.isFinite(n))
+            .sort((a, b) => a - b);
+    } catch {
+        return [];
+    }
+}
+
+(async () => {
+    let tool = '';
+    try {
+        tool = JSON.parse(await readStdin()).tool_name || '';
+    } catch {
+        /* no/invalid stdin — treat as 1 unit */
+    }
+    const units = tool.includes('download_figma_images') ? 3 : 1;
+
+    let slept = 0;
+    for (;;) {
+        const now = Math.floor(Date.now() / 1000);
+        const recent = readStamps().filter((t) => t > now - WINDOW);
+        // recent.length === 0 escape hatch: a single oversized call must never deadlock
+        if (recent.length + units <= MAX_UNITS || recent.length === 0) {
+            for (let i = 0; i < units; i++) recent.push(now);
+            fs.writeFileSync(STATE, recent.join('\n') + '\n');
+            break;
+        }
+        const wait = Math.max(1, recent[0] + WINDOW - now + 1);
+        await sleep(wait * 1000);
+        slept += wait;
+    }
+
+    if (slept > 0) {
+        console.log(
+            JSON.stringify({
+                systemMessage: `Figma rate-limit guard: delayed ${slept}s to stay under ${MAX_UNITS} calls/min`,
+            })
+        );
+    }
+    process.exit(0);
+})();

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');
@@ -210,16 +313,27 @@ function buildContextPrompt(ctx, taskState) {
         }
         lines.push(`- Gate ${currentGate}: 🔄 IN PROGRESS`);
         lines.push('');
-        lines.push(`**DO NOT restart from Gate 1.** Resume directly at Gate ${currentGate} (${gateLabel(currentGate)}).`);
+        const isGenDoc = ctx.taskType === 'gen-doc';
+        lines.push(`**DO NOT restart from Gate 1.** Resume directly at Gate ${currentGate} (${gateLabel(currentGate, ctx.taskType)}).`);
         lines.push('');
 
-        if (currentGate === 2) {
+        if (isGenDoc && currentGate >= 3) {
+            lines.push(`This is a **gen-doc** task (2-gate flow). The document workflow is complete.`);
+            lines.push(`Expected output: \`plan/${ctx.taskId}/output.md\` (or path in requirement.md).`);
+            lines.push('DO NOT start Gate 3, DO NOT create plan.md, DO NOT run TDD.');
+        } else if (currentGate === 2) {
             lines.push('Gate 1 is already APPROVED. The requirement document is at:');
             lines.push(`  AK-Docs/04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
             lines.push(`  ([functionId] — look it up in AK-Docs/04.Coding/00.Overview/_Index.md or the folder containing ${ctx.taskId}.md)`);
             lines.push('');
-            lines.push('Proceed to Gate 2: create the implementation plan.');
-            lines.push(buildModeInstruction(mode, 2));
+            if (isGenDoc) {
+                lines.push('This is a **gen-doc** task. DO NOT create plan.md or run TDD.');
+                lines.push('Proceed to Gate 2: read the approved requirement.md and generate the output document immediately.');
+                lines.push('After generating, self-review + create task-summary.md, then run `ak gate 2 approved`.');
+            } else {
+                lines.push('Proceed to Gate 2: create the implementation plan.');
+            }
+            lines.push(buildModeInstruction(mode, 2, ctx.taskType));
         } else if (currentGate === 3) {
             lines.push('Gates 1 and 2 are already APPROVED. Plans are at:');
             lines.push(`  AK-Docs/04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
@@ -265,6 +379,14 @@ function buildContextPrompt(ctx, taskState) {
         }
 
         lines.push('');
+        if (ctx.taskType === 'gen-doc') {
+            lines.push('**This is a gen-doc task (2-gate flow):**');
+            lines.push('- Gate 1: Create requirement.md → wait for APPROVED');
+            lines.push('- Gate 2 (after APPROVED): Generate output document immediately + self-review + task-summary.md');
+            lines.push('- NO plan.md, NO TDD, NO Gate 3/4/5');
+            lines.push('');
+        }
+
         lines.push('DO NOT wait for the developer to ask. START NOW.');
         lines.push('If you have not started automatically, begin as soon as the developer types **"start"**.');
         lines.push('(If a later ticket switch does not seem to trigger this — e.g. `ak use` was run in another terminal while this chat was already open — the developer can run **`/coding`** to load it manually.)');
@@ -274,7 +396,11 @@ function buildContextPrompt(ctx, taskState) {
     return lines.join('\n');
 }
 
-function gateLabel(n) {
+function gateLabel(n, taskType = '') {
+    if (taskType === 'gen-doc') {
+        if (n === 2) return 'Generate Document';
+        if (n >= 3) return 'Done';
+    }
     const labels = {
         1: 'AI Analyze Requirement',
         2: 'Implementation Plan',
@@ -285,9 +411,21 @@ function gateLabel(n) {
     return labels[n] || `Gate ${n}`;
 }
 
-function buildModeInstruction(mode, gate) {
+function buildModeInstruction(mode, gate, taskType = '') {
     if (mode !== 'fast') return '';
 
+    if (gate === 2 && taskType === 'gen-doc') {
+        return [
+            '',
+            '**MODE: fast — Gate 2 (gen-doc):**',
+            '- Re-read `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` → generate output document immediately',
+            '- Save to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` (or the custom path/format noted in the requirement doc)',
+            '- Self-review + create `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md`',
+            '- Submit AK-Docs via MR (show title/description, wait for explicit confirmation, then `ak docs submit --title "..." --description "..." --yes`)',
+            '- Run `ak gate 2 approved` immediately — NO extra approval prompt for this step',
+        ].join('\n');
+    }
+
     const instructions = {
         2: [
             '**MODE: fast** — Gate 2 fast track:',

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');
@@ -214,10 +215,30 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
     const hookBlockGitDest = path.join(hooksDir, 'block-git-write.js');
     await fs.copy(hookBlockGitSrc, hookBlockGitDest, { overwrite: true });
 
+    const hookFigmaRateSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'figma-rate-limit.js');
+    const hookFigmaRateDest = path.join(hooksDir, 'figma-rate-limit.js');
+    await fs.copy(hookFigmaRateSrc, hookFigmaRateDest, { overwrite: true });
+
+    // Hooks are CommonJS (.js + require). In an ESM project ("type": "module" in the
+    // project's package.json) Node would treat them as ES modules and crash on require().
+    // A nested package.json pins the interpretation for the kit-owned dirs only.
+    await fs.writeJson(path.join(hooksDir, 'package.json'), { type: 'commonjs' }, { spaces: 2 });
+
     // Copy telemetry module so hooks can require('../telemetry/record')
     const telemetrySrc  = path.join(PKG_DIR, 'scripts', 'telemetry');
     const telemetryDest = path.join(claudeDir, 'telemetry');
     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 = {};
@@ -273,8 +294,26 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
         ]
     });
 
+    // Throttle Figma MCP calls to stay under Figma's Tier-1 REST budget (anti-429).
+    // Sleeps when the 60s window is full — may hold a call up to ~60s, hence timeout 120.
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+        h => !(h._aiflowKitFigmaRateLimit)
+    );
+    settings.hooks.PreToolUse.push({
+        _aiflowKitFigmaRateLimit: true,
+        matcher: 'mcp__figma__.*',
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookFigmaRateDest.replace(/\\/g, '/')}"`,
+                timeout: 120,
+                statusMessage: 'Figma rate-limit guard: checking call budget…',
+            }
+        ]
+    });
+
     await fs.writeJson(settingsFile, settings, { spaces: 2 });
-    console.log(chalk.green(`✓ Superpowers hooks (SessionStart, SessionEnd, PreToolUse:block-git-write) configured`));
+    console.log(chalk.green(`✓ Superpowers hooks (SessionStart, SessionEnd, PreToolUse:block-git-write, PreToolUse:figma-rate-limit) configured`));
 }
 
 async function verifySuperpowersSkills(versionDir) {
@@ -1051,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');