@relipa/ai-flow-kit 0.0.8-beta.1 → 0.0.9-beta.0

package/bin/aiflow.js

@@ -1,400 +1,409 @@
 #!/usr/bin/env node
-
-const { program } = require('commander');
-const chalk = require('chalk');
-const packageJson = require('../package.json');
-const initCommand     = require('../scripts/init');
-const updateCommand   = require('../scripts/update');
-const doctorCommand   = require('../scripts/doctor');
-const useCommand      = require('../scripts/use');
-const TaskDetector    = require('../scripts/detect');
-const validateCommand = require('../scripts/validate');
-const memoryCommand   = require('../scripts/memory');
-const contextCommand  = require('../scripts/context');
-const promptCommand   = require('../scripts/prompt');
-const removeCommand   = require('../scripts/remove');
-const guideCommand    = require('../scripts/guide');
-const telemetryCommand= require('../scripts/telemetry/cli');
-const taskCommand     = require('../scripts/task');
-const checkpointCommand = require('../scripts/checkpoint');
-const { record }      = require('../scripts/telemetry/record');
-
-// ── DEPRECATION WARNING ───────────────────────────────────────
-if (!process.env.AIFLOW_IS_AK) {
-    console.warn(chalk.yellow('\n⚠ Warning: "aiflow" command is deprecated and will be removed in future versions.'));
-    console.warn(chalk.yellow('Please use the shorter "ak" command instead.\n'));
-}
-
-program
-    .version(packageJson.version)
-    .description('AI Flow Kit CLI - AI-powered development workflows for teams');
-
-// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
-// We intercept raw argv here so we can catch --version, --help,
-// and invalid commands *before* Commander exits the process.
-// Also alias `-v` to commander's `-V` at the root only — subcommands still
-// keep `-v` as `--verbose`. And alias `--fw` to `--framework`.
-(() => {
-    if (process.argv[2] === '-v') process.argv[2] = '-V';
-    for (let i = 3; i < process.argv.length; i++) {
-        if (process.argv[i] === '--fw') process.argv[i] = '--framework';
-    }
-    const args = process.argv.slice(2);
-    let cmd = 'help';
-    if (args.length > 0) {
-        const first = args[0];
-        if (['-V', '-v', '--version'].includes(first)) {
-            cmd = 'version';
-        } else if (['-h', '--help'].includes(first)) {
-            cmd = 'help';
-        } else if (first.startsWith('-')) {
-            cmd = 'unknown_flag';
-            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
-        } else if (first === 'memory') {
-            const sec = args[1];
-            cmd = (sec && !sec.startsWith('-')) ? `memory.${sec}` : 'memory';
-        } else {
-            cmd = first;
-            if (args.includes('--help') || args.includes('-h')) {
-                cmd = `${first}.help`;
-            }
-        }
-    }
-    // Record everything except telemetry and gate actions (gate records its own rich event)
-    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
-        record('command.invoked', { command: cmd });
-    }
-})();
-
-
-// ── init ──────────────────────────────────────────────────────
-program
-    .command('init')
-    .alias('i')
-    .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('--with-rtk', 'force enable RTK token compression hook')
-    .option('--no-rtk', 'skip RTK setup even if RTK is detected')
-    .action((options) => {
-        options.frameworks = options.framework
-            ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
-            : [];
-        options.adapters = options.adapter
-            ? options.adapter.split(',').map(s => s.trim()).filter(Boolean)
-            : [];
-        options.aiTools = options.env
-            ? options.env.split(',').map(s => s.trim()).filter(Boolean)
-            : Object.keys(require('../scripts/init').AI_TOOL_FILES || {}).filter(t => t !== 'generic');
-
-        record('command.invoked', { command: 'init' });
-        initCommand(options);
-    });
-
-// ── use ───────────────────────────────────────────────────────
-program
-    .command('use [target]')
-    .alias('u')
-    .description('Load context from ticket, version, or file')
-    .option('-m, --manual', 'manual context entry')
-    .option('-f, --file <path>', 'load from file')
-    .option('-s, --save <name>', 'save as named context')
-    .option('-c, --coms', 'load all comments (alias for --with-comments)')
-    .option('--with-comments', 'load all comments')
-    .option('--cid <id>', 'load a specific comment by ID')
-    .option('--clast <n>', 'load the last N comments', parseInt)
-    .option('--cfrom <id>', 'load comments from ID N onward', parseInt)
-    .option('--cto <id>', 'load comments up to ID N', parseInt)
-    .option('-F, --fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
-    .option('-U, --full', 'full mode: force complete analysis with Q&A (default)')
-    .action((target, options) => {
-        record('command.invoked', { command: 'use' });
-        useCommand(target, options);
-    });
-
-// ── prompt ────────────────────────────────────────────────────
-program
-    .command('prompt [type]')
-    .alias('p')
-    .description('Generate AI prompt with context and rules')
-    .option('-l, --list', 'list available prompt types')
-    .option('-o, --output <file>', 'save to file')
-    .option('-L, --lang <lang>', 'language: english (default) or vietnamese')
-    .option('-d, --detail <level>', 'detail level: minimal | standard (default) | comprehensive')
-    .action((type, options) => {
-        record('command.invoked', { command: 'prompt' });
-        promptCommand(type, options);
-    });
-
-// ── detect ────────────────────────────────────────────────────
-program
-    .command('detect [description]')
-    .alias('d')
-    .description('Auto-detect task type from description')
-    .option('-v, --verbose', 'show detection details')
-    .option('-t, --threshold <number>', 'confidence threshold (0-100)')
-    .action((description, options) => {
-        record('command.invoked', { command: 'detect' });
-        const detector = new TaskDetector();
-        const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
-        const result = detector.detect(description, threshold);
-        console.log(chalk.cyan('\nTask Detection Results:\n'));
-        console.log(detector.formatOutput(result, options.verbose));
-    });
-
-// ── task ─────────────────────────────────────────────────────
-const taskCmd = program.command('task').alias('t').description('Manage multiple tasks — pause, switch, resume');
-
-taskCmd
-    .command('status')
-    .alias('st')
-    .description('Show active task and pending tasks')
-    .action(() => { record('command.invoked', { command: 'task.status' }); taskCommand('status'); });
-
-taskCmd
-    .command('list')
-    .alias('ls')
-    .description('List all saved tasks')
-    .action(() => { record('command.invoked', { command: 'task.list' }); taskCommand('list'); });
-
-taskCmd
-    .command('pause')
-    .alias('p')
-    .description('Pause current task and save progress')
-    .option('-n, --note <text>', 'note about why you are pausing')
-    .action((opts) => { record('command.invoked', { command: 'task.pause' }); taskCommand('pause', { note: opts.note }); });
-
-taskCmd
-    .command('switch <ticket-id>')
-    .alias('sw')
-    .description('Pause current task and switch to another')
-    .action((ticketId) => { record('command.invoked', { command: 'task.switch' }); taskCommand('switch', { taskId: ticketId }); });
-
-taskCmd
-    .command('resume <ticket-id>')
-    .alias('r')
-    .description('Resume a paused task')
-    .action((ticketId) => { record('command.invoked', { command: 'task.resume' }); taskCommand('resume', { taskId: ticketId }); });
-
-taskCmd
-    .command('reset <ticket-id>')
-    .alias('rst')
-    .description('Reset task to Gate 1 (keeps ticket context, clears gate progress)')
-    .action((ticketId) => { record('command.invoked', { command: 'task.reset' }); taskCommand('reset', { taskId: ticketId }); });
-
-taskCmd
-    .command('remove <ticket-id>')
-    .alias('rm')
-    .description('Permanently delete all saved data for a task')
-    .action((ticketId) => { record('command.invoked', { command: 'task.remove' }); taskCommand('remove', { taskId: ticketId }); });
-
-taskCmd
-    .command('next')
-    .alias('n')
-    .description('Approve current gate and prepare next session (saves state for resume)')
-    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
-    .action((opts) => {
-        record('command.invoked', { command: 'task.next' });
-        taskCommand('next', { taskId: opts.ticket });
-    });
-
-// ── context ───────────────────────────────────────────────────
-program
-    .command('context [action]')
-    .alias('ctx')
-    .description('Manage task contexts (list|show|save <name>|clear)')
-    .option('-s, --save <name>', 'save current context with name')
-    .option('-l, --load <name>', 'load saved context by name')
-    .option('-d, --delete <name>', 'delete saved context')
-    .option('--clear', 'clear all saved contexts')
-    .option('--show', 'show current context')
-    .action((action, options) => {
-        record('command.invoked', { command: 'context' });
-        contextCommand(action, options);
-    });
-
-// ── checkpoint ────────────────────────────────────────────────
-program
-    .command('checkpoint')
-    .alias('cp')
-    .description('Record token usage checkpoint (called by AI during gate work)')
-    .requiredOption('-g, --gate <n>', 'gate number (1–5)', parseInt)
-    .requiredOption('-s, --step <name>', 'step name (e.g. "tests-written")')
-    .requiredOption('-n, --tokens <n>', 'estimated token count', parseInt)
-    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
-    .action((opts) => {
-        record('command.invoked', { command: 'checkpoint' });
-        checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
-    });
-
-// ── validate ──────────────────────────────────────────────────
-program
-    .command('validate <file>')
-    .alias('vl')
-    .description('Validate output against team rules')
-    .option('-r, --ruleset <set>', 'rule set: default | strict | lenient', 'default')
-    .option('-v, --verbose', 'detailed report')
-    .option('-x, --fix', 'auto-fix trailing whitespace')
-    .action((file, options) => {
-        record('command.invoked', { command: 'validate' });
-        validateCommand(file, {
-            ruleset: options.ruleset,
-            verbose: options.verbose,
-            fix: options.fix
-        });
-    });
-
-// ── 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) => { record('command.invoked', { command: 'memory.save' }); memoryCommand('save', { key, value }); });
-
-memCmd
-    .command('get <key>')
-    .alias('g')
-    .description('Retrieve a memory entry')
-    .action((key) => { record('command.invoked', { command: 'memory.get' }); memoryCommand('get', { key }); });
-
-memCmd
-    .command('list')
-    .alias('ls')
-    .description('List all memories')
-    .action(() => { record('command.invoked', { command: 'memory.list' }); memoryCommand('list'); });
-
-memCmd
-    .command('search <query>')
-    .alias('sr')
-    .description('Search memories by keyword')
-    .action((query) => { record('command.invoked', { command: 'memory.search' }); memoryCommand('search', { query }); });
-
-memCmd
-    .command('delete <key>')
-    .alias('d')
-    .description('Delete a memory entry')
-    .action((key) => { record('command.invoked', { command: 'memory.delete' }); memoryCommand('delete', { key }); });
-
-memCmd
-    .command('clear')
-    .alias('cl')
-    .description('Clear all memories')
-    .action(() => { record('command.invoked', { command: 'memory.clear' }); memoryCommand('clear'); });
-
-// ── guide ─────────────────────────────────────────────────────
-program
-    .command('guide')
-    .alias('g')
-    .description('Show quickstart guide, architecture, and command reference')
-    .option('-f, --flow', 'show architecture & flow diagram only')
-    .option('-c, --commands', 'show command reference only')
-    .action((options) => {
-        record('command.invoked', { command: 'guide' });
-        guideCommand(options);
-    });
-
-// ── gate (telemetry for gate workflow events) ─────────────────
-program
-    .command('gate <number> <action>')
-    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
-    .option('--ticket <id>', 'ticket ID')
-    .option('--ai-tool <tool>', 'AI tool name')
-    .action((number, action, options) => {
-        const gateNum = parseInt(number);
-        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
-        if (!['start', 'approved'].includes(action)) return;
-        record(`gate.${action}`, {
-            gate: gateNum,
-            ticket_id: options.ticket || '',
-            command: `gate${gateNum}.${action}`,
-            ai_tool: options.aiTool || ''
-        });
-
-        if (action === 'approved') {
-            console.log(chalk.cyan(`\n  Gate ${gateNum} approved!`));
-            console.log(chalk.yellow(`  Pro-Tip: To avoid context pollution, it's recommended to start a fresh chat session.`));
-            console.log(chalk.gray(`  Run: aiflow task next${options.ticket ? ` --ticket ${options.ticket}` : ''} to save progress,`));
-            console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
-        }
-    });
-
-// ── remove ────────────────────────────────────────────────────
-program
-    .command('remove')
-    .alias('rm')
-    .description('Remove ai-flow-kit from project, a cached version, or uninstall globally')
-    .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
-    .option('-g, --global', 'uninstall the global npm package (removes `aiflow` command)')
-    .action((options) => {
-        record('command.invoked', { command: 'remove' });
-        removeCommand(options);
-    });
-
-// ── update ────────────────────────────────────────────────────
-program
-    .command('update')
-    .alias('up')
-    .description('Update to latest version')
-    .option('-f, --force', 'force update even if already on latest')
-    .action((options) => {
-        record('command.invoked', { command: 'update' });
-        updateCommand(options);
-    });
-
-// ── sync-skills ───────────────────────────────────────────────
-program
-    .command('sync-skills')
-    .alias('sync')
-    .description('Manually synchronize AI Instruction files with local custom skills')
-    .action(async () => {
-        record('command.invoked', { command: 'sync-skills' });
-        const projectDir = process.cwd();
-        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
-        const fs = require('fs-extra');
-        const path = require('path');
-        const chalk = require('chalk');
-
-        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
-        if (!(await fs.pathExists(stateFile))) {
-            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
-            return;
-        }
-
-        const state = await fs.readJson(stateFile);
-        const frameworks = state.frameworks || [];
-        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
-
-        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
-        for (const fw of frameworks) {
-            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
-        }
-        await ensureAiflowGitignored(projectDir);
-        console.log(chalk.green('✨ Sync completed!'));
-    });
-
-// ── doctor ────────────────────────────────────────────────────
-program
-    .command('doctor')
-    .alias('dr')
-    .description('Health check of AI Flow Kit setup')
-    .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
-    .option('-v, --verbose', 'detailed output')
-    .action((opts) => {
-        record('command.invoked', { command: 'doctor' });
-        doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
-    });
-
-// ── telemetry ──────────────────────────────────────────────────
-program
-    .command('telemetry [action]')
-    .alias('tel')
-    .description('Manage telemetry logging (enable|disable|status)')
-    .action((action) => {
-        telemetryCommand(action || 'status');
-    });
-
-program.parse(process.argv);
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const packageJson = require('../package.json');
+const initCommand     = require('../scripts/init');
+const updateCommand   = require('../scripts/update');
+const doctorCommand   = require('../scripts/doctor');
+const useCommand      = require('../scripts/use');
+const TaskDetector    = require('../scripts/detect');
+const validateCommand = require('../scripts/validate');
+const memoryCommand   = require('../scripts/memory');
+const contextCommand  = require('../scripts/context');
+const promptCommand   = require('../scripts/prompt');
+const removeCommand   = require('../scripts/remove');
+const guideCommand    = require('../scripts/guide');
+const telemetryCommand= require('../scripts/telemetry/cli');
+const taskCommand     = require('../scripts/task');
+const checkpointCommand = require('../scripts/checkpoint');
+const { record }      = require('../scripts/telemetry/record');
+const { updateTaskGateState } = require('../scripts/task');
+
+// ── DEPRECATION WARNING ───────────────────────────────────────
+if (!process.env.AIFLOW_IS_AK) {
+    console.warn(chalk.yellow('\n⚠ Warning: "aiflow" command is deprecated and will be removed in future versions.'));
+    console.warn(chalk.yellow('Please use the shorter "ak" command instead.\n'));
+}
+
+program
+    .version(packageJson.version)
+    .description('AI Flow Kit CLI - AI-powered development workflows for teams');
+
+// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
+// We intercept raw argv here so we can catch --version, --help,
+// and invalid commands *before* Commander exits the process.
+// Also alias `-v` to commander's `-V` at the root only — subcommands still
+// keep `-v` as `--verbose`. And alias `--fw` to `--framework`.
+(() => {
+    if (process.argv[2] === '-v') process.argv[2] = '-V';
+    for (let i = 3; i < process.argv.length; i++) {
+        if (process.argv[i] === '--fw') process.argv[i] = '--framework';
+    }
+    const args = process.argv.slice(2);
+    let cmd = 'help';
+    if (args.length > 0) {
+        const first = args[0];
+        if (['-V', '-v', '--version'].includes(first)) {
+            cmd = 'version';
+        } else if (['-h', '--help'].includes(first)) {
+            cmd = 'help';
+        } else if (first.startsWith('-')) {
+            cmd = 'unknown_flag';
+            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
+        } else if (first === 'memory') {
+            const sec = args[1];
+            cmd = (sec && !sec.startsWith('-')) ? `memory.${sec}` : 'memory';
+        } else {
+            cmd = first;
+            if (args.includes('--help') || args.includes('-h')) {
+                cmd = `${first}.help`;
+            }
+        }
+    }
+    // Record everything except telemetry and gate actions (gate records its own rich event)
+    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
+        record('command.invoked', { command: cmd });
+    }
+})();
+
+
+// ── init ──────────────────────────────────────────────────────
+program
+    .command('init')
+    .alias('i')
+    .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('--with-rtk', 'force enable RTK token compression hook')
+    .option('--no-rtk', 'skip RTK setup even if RTK is detected')
+    .action((options) => {
+        options.frameworks = options.framework
+            ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
+            : [];
+        options.adapters = options.adapter
+            ? options.adapter.split(',').map(s => s.trim()).filter(Boolean)
+            : [];
+        options.aiTools = options.env
+            ? options.env.split(',').map(s => s.trim()).filter(Boolean)
+            : Object.keys(require('../scripts/init').AI_TOOL_FILES || {}).filter(t => t !== 'generic');
+
+        record('command.invoked', { command: 'init' });
+        initCommand(options);
+    });
+
+// ── use ───────────────────────────────────────────────────────
+program
+    .command('use [target]')
+    .alias('u')
+    .description('Load context from ticket, version, or file')
+    .option('-m, --manual', 'manual context entry')
+    .option('-f, --file <path>', 'load from file')
+    .option('-s, --save <name>', 'save as named context')
+    .option('-c, --coms', 'load all comments (alias for --with-comments)')
+    .option('--with-comments', 'load all comments')
+    .option('--cid <id>', 'load a specific comment by ID')
+    .option('--clast <n>', 'load the last N comments', parseInt)
+    .option('--cfrom <id>', 'load comments from ID N onward', parseInt)
+    .option('--cto <id>', 'load comments up to ID N', parseInt)
+    .option('-F, --fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
+    .option('-U, --full', 'full mode: force complete analysis with Q&A (default)')
+    .action((target, options) => {
+        record('command.invoked', { command: 'use' });
+        useCommand(target, options);
+    });
+
+// ── prompt ────────────────────────────────────────────────────
+program
+    .command('prompt [type]')
+    .alias('p')
+    .description('Generate AI prompt with context and rules')
+    .option('-l, --list', 'list available prompt types')
+    .option('-o, --output <file>', 'save to file')
+    .option('-L, --lang <lang>', 'language: english (default) or vietnamese')
+    .option('-d, --detail <level>', 'detail level: minimal | standard (default) | comprehensive')
+    .action((type, options) => {
+        record('command.invoked', { command: 'prompt' });
+        promptCommand(type, options);
+    });
+
+// ── detect ────────────────────────────────────────────────────
+program
+    .command('detect [description]')
+    .alias('d')
+    .description('Auto-detect task type from description')
+    .option('-v, --verbose', 'show detection details')
+    .option('-t, --threshold <number>', 'confidence threshold (0-100)')
+    .action((description, options) => {
+        record('command.invoked', { command: 'detect' });
+        const detector = new TaskDetector();
+        const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
+        const result = detector.detect(description, threshold);
+        console.log(chalk.cyan('\nTask Detection Results:\n'));
+        console.log(detector.formatOutput(result, options.verbose));
+    });
+
+// ── task ─────────────────────────────────────────────────────
+const taskCmd = program.command('task').alias('t').description('Manage multiple tasks — pause, switch, resume');
+
+taskCmd
+    .command('status')
+    .alias('st')
+    .description('Show active task and pending tasks')
+    .action(() => { record('command.invoked', { command: 'task.status' }); taskCommand('status'); });
+
+taskCmd
+    .command('list')
+    .alias('ls')
+    .description('List all saved tasks')
+    .action(() => { record('command.invoked', { command: 'task.list' }); taskCommand('list'); });
+
+taskCmd
+    .command('pause')
+    .alias('p')
+    .description('Pause current task and save progress')
+    .option('-n, --note <text>', 'note about why you are pausing')
+    .action((opts) => { record('command.invoked', { command: 'task.pause' }); taskCommand('pause', { note: opts.note }); });
+
+taskCmd
+    .command('switch <ticket-id>')
+    .alias('sw')
+    .description('Pause current task and switch to another')
+    .action((ticketId) => { record('command.invoked', { command: 'task.switch' }); taskCommand('switch', { taskId: ticketId }); });
+
+taskCmd
+    .command('resume <ticket-id>')
+    .alias('r')
+    .description('Resume a paused task')
+    .action((ticketId) => { record('command.invoked', { command: 'task.resume' }); taskCommand('resume', { taskId: ticketId }); });
+
+taskCmd
+    .command('reset <ticket-id>')
+    .alias('rst')
+    .description('Reset task to Gate 1 (keeps ticket context, clears gate progress)')
+    .action((ticketId) => { record('command.invoked', { command: 'task.reset' }); taskCommand('reset', { taskId: ticketId }); });
+
+taskCmd
+    .command('remove <ticket-id>')
+    .alias('rm')
+    .description('Permanently delete all saved data for a task')
+    .action((ticketId) => { record('command.invoked', { command: 'task.remove' }); taskCommand('remove', { taskId: ticketId }); });
+
+taskCmd
+    .command('next')
+    .alias('n')
+    .description('Approve current gate and prepare next session (saves state for resume)')
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        record('command.invoked', { command: 'task.next' });
+        taskCommand('next', { taskId: opts.ticket });
+    });
+
+// ── context ───────────────────────────────────────────────────
+program
+    .command('context [action]')
+    .alias('ctx')
+    .description('Manage task contexts (list|show|save <name>|clear)')
+    .option('-s, --save <name>', 'save current context with name')
+    .option('-l, --load <name>', 'load saved context by name')
+    .option('-d, --delete <name>', 'delete saved context')
+    .option('--clear', 'clear all saved contexts')
+    .option('--show', 'show current context')
+    .action((action, options) => {
+        record('command.invoked', { command: 'context' });
+        contextCommand(action, options);
+    });
+
+// ── checkpoint ────────────────────────────────────────────────
+program
+    .command('checkpoint')
+    .alias('cp')
+    .description('Record token usage checkpoint (called by AI during gate work)')
+    .requiredOption('-g, --gate <n>', 'gate number (1–5)', parseInt)
+    .requiredOption('-s, --step <name>', 'step name (e.g. "tests-written")')
+    .requiredOption('-n, --tokens <n>', 'estimated token count', parseInt)
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        record('command.invoked', { command: 'checkpoint' });
+        checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
+    });
+
+// ── validate ──────────────────────────────────────────────────
+program
+    .command('validate <file>')
+    .alias('vl')
+    .description('Validate output against team rules')
+    .option('-r, --ruleset <set>', 'rule set: default | strict | lenient', 'default')
+    .option('-v, --verbose', 'detailed report')
+    .option('-x, --fix', 'auto-fix trailing whitespace')
+    .action((file, options) => {
+        record('command.invoked', { command: 'validate' });
+        validateCommand(file, {
+            ruleset: options.ruleset,
+            verbose: options.verbose,
+            fix: options.fix
+        });
+    });
+
+// ── 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) => { record('command.invoked', { command: 'memory.save' }); memoryCommand('save', { key, value }); });
+
+memCmd
+    .command('get <key>')
+    .alias('g')
+    .description('Retrieve a memory entry')
+    .action((key) => { record('command.invoked', { command: 'memory.get' }); memoryCommand('get', { key }); });
+
+memCmd
+    .command('list')
+    .alias('ls')
+    .description('List all memories')
+    .action(() => { record('command.invoked', { command: 'memory.list' }); memoryCommand('list'); });
+
+memCmd
+    .command('search <query>')
+    .alias('sr')
+    .description('Search memories by keyword')
+    .action((query) => { record('command.invoked', { command: 'memory.search' }); memoryCommand('search', { query }); });
+
+memCmd
+    .command('delete <key>')
+    .alias('d')
+    .description('Delete a memory entry')
+    .action((key) => { record('command.invoked', { command: 'memory.delete' }); memoryCommand('delete', { key }); });
+
+memCmd
+    .command('clear')
+    .alias('cl')
+    .description('Clear all memories')
+    .action(() => { record('command.invoked', { command: 'memory.clear' }); memoryCommand('clear'); });
+
+// ── guide ─────────────────────────────────────────────────────
+program
+    .command('guide')
+    .alias('g')
+    .description('Show quickstart guide, architecture, and command reference')
+    .option('-f, --flow', 'show architecture & flow diagram only')
+    .option('-c, --commands', 'show command reference only')
+    .action((options) => {
+        record('command.invoked', { command: 'guide' });
+        guideCommand(options);
+    });
+
+// ── gate (telemetry for gate workflow events) ─────────────────
+program
+    .command('gate <number> <action>')
+    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
+    .option('--ticket <id>', 'ticket ID')
+    .option('--ai-tool <tool>', 'AI tool name')
+    .action((number, action, options) => {
+        const gateNum = parseInt(number);
+        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
+        if (!['start', 'approved'].includes(action)) return;
+
+        const ticketId = options.ticket || '';
+
+        record(`gate.${action}`, {
+            gate: gateNum,
+            ticket_id: ticketId,
+            command: `gate${gateNum}.${action}`,
+            ai_tool: options.aiTool || ''
+        });
+
+        // Keep task-state.json currentGate in sync (silent — never blocks the AI)
+        if (ticketId) {
+            updateTaskGateState(ticketId, gateNum, action).catch(() => {});
+        }
+
+        if (action === 'approved') {
+            console.log(chalk.cyan(`\n  Gate ${gateNum} approved!`));
+            console.log(chalk.yellow(`  Pro-Tip: To avoid context pollution, it's recommended to start a fresh chat session.`));
+            console.log(chalk.gray(`  Run: aiflow task next${ticketId ? ` --ticket ${ticketId}` : ''} to save progress,`));
+            console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
+        }
+    });
+
+// ── remove ────────────────────────────────────────────────────
+program
+    .command('remove')
+    .alias('rm')
+    .description('Remove ai-flow-kit from project, a cached version, or uninstall globally')
+    .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
+    .option('-g, --global', 'uninstall the global npm package (removes `aiflow` command)')
+    .action((options) => {
+        record('command.invoked', { command: 'remove' });
+        removeCommand(options);
+    });
+
+// ── update ────────────────────────────────────────────────────
+program
+    .command('update')
+    .alias('up')
+    .description('Update to latest version')
+    .option('-f, --force', 'force update even if already on latest')
+    .action((options) => {
+        record('command.invoked', { command: 'update' });
+        updateCommand(options);
+    });
+
+// ── sync-skills ───────────────────────────────────────────────
+program
+    .command('sync-skills')
+    .alias('sync')
+    .description('Manually synchronize AI Instruction files with local custom skills')
+    .action(async () => {
+        record('command.invoked', { command: 'sync-skills' });
+        const projectDir = process.cwd();
+        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
+        const fs = require('fs-extra');
+        const path = require('path');
+        const chalk = require('chalk');
+
+        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+        if (!(await fs.pathExists(stateFile))) {
+            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
+            return;
+        }
+
+        const state = await fs.readJson(stateFile);
+        const frameworks = state.frameworks || [];
+        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
+
+        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
+        for (const fw of frameworks) {
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
+        }
+        await ensureAiflowGitignored(projectDir);
+        console.log(chalk.green('✨ Sync completed!'));
+    });
+
+// ── doctor ────────────────────────────────────────────────────
+program
+    .command('doctor')
+    .alias('dr')
+    .description('Health check of AI Flow Kit setup')
+    .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
+    .option('-v, --verbose', 'detailed output')
+    .action((opts) => {
+        record('command.invoked', { command: 'doctor' });
+        doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
+    });
+
+// ── telemetry ──────────────────────────────────────────────────
+program
+    .command('telemetry [action]')
+    .alias('tel')
+    .description('Manage telemetry logging (enable|disable|status)')
+    .action((action) => {
+        telemetryCommand(action || 'status');
+    });
+
+program.parse(process.argv);