@relipa/ai-flow-kit 0.0.6 → 0.0.7-beta.0

package/package.json

@@ -1,13 +1,8 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.6",
+  "version": "0.0.7-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
-  "author": "Relipa AI Team",
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.relipa.vn/ai/ai-flow-kit.git"
-  },
-  "homepage": "https://gitlab.relipa.vn/ai/ai-flow-kit#readme",
+  "author": "Example Team",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.com/"

package/scripts/checkpoint.js

@@ -0,0 +1,46 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const PROJECT_DIR  = process.cwd();
+const AIFLOW_DIR   = path.join(PROJECT_DIR, '.aiflow');
+const CONTEXT_FILE = path.join(AIFLOW_DIR, 'context', 'current.json');
+
+const GATE_LABELS = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+
+module.exports = async function checkpoint(options = {}) {
+    const { gate, step, tokens, ticket: ticketOpt } = options;
+
+    if (!gate || !step || tokens === undefined) {
+        console.log(chalk.yellow('Usage: aiflow checkpoint --gate <N> --step <name> --tokens <N>'));
+        console.log(chalk.gray('  Example: aiflow checkpoint --gate 3 --step "tests-written" --tokens 3200'));
+        return;
+    }
+
+    // Resolve ticket ID
+    let ticketId = ticketOpt;
+    if (!ticketId) {
+        const ctx = await fs.readJson(CONTEXT_FILE).catch(() => null);
+        ticketId = ctx && ctx.taskId ? ctx.taskId : 'unknown';
+    }
+
+    const taskDir = path.join(AIFLOW_DIR, 'tasks', ticketId);
+    await fs.ensureDir(taskDir);
+
+    const checkpointPath = path.join(taskDir, 'checkpoints.json');
+    const existing = (await fs.pathExists(checkpointPath))
+        ? await fs.readJson(checkpointPath).catch(() => ({ checkpoints: [] }))
+        : { checkpoints: [] };
+
+    const entry = {
+        gate:      parseInt(gate),
+        step,
+        tokens:    parseInt(tokens),
+        timestamp: new Date().toISOString(),
+    };
+    existing.checkpoints.push(entry);
+    await fs.writeJson(checkpointPath, existing, { spaces: 2 });
+
+    const label = GATE_LABELS[parseInt(gate)] || `Gate ${gate}`;
+    console.log(chalk.green(`✓ Checkpoint: Gate ${gate} (${label}) — ${step} — ~${parseInt(tokens).toLocaleString()} tokens`));
+};

package/scripts/doctor.js

@@ -1,15 +1,71 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
-const { detectRtk, isRtkHookConfigured } = require('./init');
+const { detectRtk, isRtkHookConfigured, isGitNexusConfigured } = require('./init');
 
-module.exports = async function doctor() {
+function formatAgo(isoString) {
+    const ms = Date.now() - new Date(isoString).getTime();
+    const mins = Math.floor(ms / 60000);
+    if (mins < 1)   return 'just now';
+    if (mins < 60)  return `${mins}m ago`;
+    const hrs = Math.floor(mins / 60);
+    if (hrs < 24)   return `${hrs}h ago`;
+    return `${Math.floor(hrs / 24)}d ago`;
+}
+
+async function showTokenBreakdown(ticketId) {
+    const tasksDir = path.join(process.cwd(), '.aiflow', 'tasks');
+    const checkpointsFile = path.join(tasksDir, ticketId, 'checkpoints.json');
+    if (!(await fs.pathExists(checkpointsFile))) return;
+
+    const data = await fs.readJson(checkpointsFile).catch(() => ({ checkpoints: [] }));
+    if (!data.checkpoints || data.checkpoints.length === 0) return;
+
+    // Aggregate tokens per gate (taking the max/latest)
+    const gateTokens = {};
+    for (const cp of data.checkpoints) {
+        if (!gateTokens[cp.gate] || cp.tokens > gateTokens[cp.gate]) {
+            gateTokens[cp.gate] = cp.tokens;
+        }
+    }
+
+    const GATE_LABELS = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+    const gates = Object.keys(gateTokens).sort();
+    const total = gates.reduce((sum, g) => sum + gateTokens[g], 0);
+
+    console.log('');
+    console.log(chalk.bold(`Token usage for task ${ticketId}:`));
+    for (const g of gates) {
+        const label = GATE_LABELS[parseInt(g)] || `Gate ${g}`;
+        const t = gateTokens[g];
+        const bar = '█'.repeat(Math.round((t / total) * 20)).padEnd(20, '░');
+        const pct = Math.round((t / total) * 100);
+        console.log(`  Gate ${g}  ${label.padEnd(8)}  ~${t.toLocaleString().padStart(6)}  ${chalk.gray(bar)}  ${pct}%`);
+    }
+    console.log(`  Total estimated: ~${total.toLocaleString()} tokens`);
+}
+
+module.exports = async function doctor(options = {}) {
     const projectDir = process.cwd();
     const errors = [];
     const warnings = [];
 
     console.log(chalk.blue('Running health check for AI Flow Kit...\n'));
 
+    // ── Token breakdown ────────────────────────────────────────
+    let ticketId = options.ticket;
+    if (!ticketId) {
+        const contextFile = path.join(projectDir, '.aiflow', 'context', 'current.json');
+        if (await fs.pathExists(contextFile)) {
+            const ctx = await fs.readJson(contextFile).catch(() => ({}));
+            ticketId = ctx.taskId;
+        }
+    }
+
+    if (ticketId) {
+        await showTokenBreakdown(ticketId);
+    }
+
     // ── Core setup ─────────────────────────────────────────────
     if (!(await fs.pathExists(path.join(projectDir, '.claude', 'skills')))) {
         errors.push('Missing `.claude/skills` directory. Did you run `aiflow init`?');
@@ -55,20 +111,67 @@ module.exports = async function doctor() {
         warnings.push('Missing .claude/settings.json — run `aiflow init`.');
     }
 
-    // ── RTK token compression ──────────────────────────────────
+    // ── Token savings tools ────────────────────────────────────
     console.log('');
+    console.log(chalk.bold('Token savings:'));
+
+    // RTK
     const rtk = await detectRtk();
     if (rtk.installed) {
         const hookOk = await isRtkHookConfigured(projectDir);
         if (hookOk) {
-            console.log(chalk.green(`✓ RTK installed (${rtk.version}) — token compression active`));
+            console.log(chalk.green(`  ✓ RTK (${rtk.version}) — bash output compression active`));
+            console.log(chalk.gray('    Estimated: 60–90% reduction on bash command outputs (test runs, git, npm...)'));
         } else {
-            console.log(chalk.green(`✓ RTK installed (${rtk.version})`));
-            warnings.push('RTK is installed but hook not configured. Run `aiflow init` to enable token compression.');
+            console.log(chalk.yellow(`  ⚠ RTK installed (${rtk.version}) but hook not configured`));
+            warnings.push('RTK hook not configured. Run `aiflow init` to enable token compression.');
+        }
+    } else {
+        console.log(chalk.gray('  ○ RTK not installed — bash output compression inactive'));
+        console.log(chalk.gray('    Install: cargo install rtk  |  Enable: aiflow init --with-rtk'));
+    }
+
+    // GitNexus
+    const gnConfigured = await isGitNexusConfigured(projectDir);
+    const gnStatusPath = path.join(projectDir, '.aiflow', 'gitnexus-status.json');
+    if (gnConfigured) {
+        let statusLine = chalk.green('  ✓ GitNexus MCP configured');
+        try {
+            if (await fs.pathExists(gnStatusPath)) {
+                const gn = await fs.readJson(gnStatusPath);
+                const GITNEXUS_STALE_MS = 3 * 60 * 60 * 1000; // 3 hours
+                if (gn.status === 'done') {
+                    const ago = gn.completedAt
+                        ? chalk.gray(` — indexed ${formatAgo(gn.completedAt)}`)
+                        : '';
+                    statusLine = chalk.green(`  ✓ GitNexus MCP configured — index ready${ago}`);
+                    console.log(statusLine);
+                    console.log(chalk.gray('    Estimated: ~50% fewer tokens at Gate 1 (context queries vs file reads)'));
+                    console.log(chalk.gray('    Estimated: ~70% fewer tokens at Gate 4 (impact() vs grep codebase)'));
+                } else if (gn.status === 'running') {
+                    const age = Date.now() - new Date(gn.startedAt).getTime();
+                    if (age > GITNEXUS_STALE_MS) {
+                        console.log(chalk.red('  ✗ GitNexus MCP configured — indexing timed out (stale)'));
+                        console.log(chalk.gray(`    Started ${formatAgo(gn.startedAt)} but never finished. Process may have crashed.`));
+                        // console.log(chalk.gray('    Retry: aiflow init --with-gitnexus --wait  |  Log: .aiflow/gitnexus-analyze.log'));
+                    } else {
+                        console.log(chalk.yellow('  ⟳ GitNexus MCP configured — indexing in progress...'));
+                        console.log(chalk.gray('    Log: .aiflow/gitnexus-analyze.log'));
+                    }
+                } else if (gn.status === 'error') {
+                    console.log(chalk.red('  ✗ GitNexus MCP configured — last index failed'));
+                    console.log(chalk.gray('    Retry: npx gitnexus analyze  |  Log: .aiflow/gitnexus-analyze.log'));
+                }
+            } else {
+                console.log(chalk.yellow('  ⚠ GitNexus MCP configured but not yet indexed'));
+                console.log(chalk.gray('    Run: npx gitnexus analyze'));
+            }
+        } catch (_) {
+            console.log(statusLine);
         }
     } else {
-        console.log(chalk.gray('○ RTK not installed (optional) — token compression inactive'));
-        console.log(chalk.gray('  Install: cargo install rtk  |  More: https://github.com/rtk-ai/rtk'));
+        console.log(chalk.gray('  ○ GitNexus not configured — code intelligence inactive'));
+        // console.log(chalk.gray('    Enable: aiflow init --with-gitnexus'));
     }
 
     // ── Summary ────────────────────────────────────────────────

package/scripts/gitnexus-worker.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Background worker: runs `npx gitnexus analyze` and writes result to
+ * .aiflow/gitnexus-status.json so session-start.js / use.js can notify the developer.
+ *
+ * Spawned as a detached process by init.js — never run directly.
+ * Usage: node gitnexus-worker.js <projectDir>
+ */
+
+const { spawn, execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function commandExists(cmd) {
+    try {
+        const isWin = process.platform === 'win32';
+        const checkCmd = isWin ? `where ${cmd}` : `which ${cmd}`;
+        execSync(checkCmd, { stdio: 'ignore' });
+        return true;
+    } catch (_) {
+        return false;
+    }
+}
+
+const projectDir = process.argv[2];
+if (!projectDir) process.exit(1);
+
+const statusPath = path.join(projectDir, '.aiflow', 'gitnexus-status.json');
+const logPath    = path.join(projectDir, '.aiflow', 'gitnexus-analyze.log');
+
+// Preserve startedAt written by init.js
+let startedAt = new Date().toISOString();
+try {
+    if (fs.existsSync(statusPath)) {
+        const existing = JSON.parse(fs.readFileSync(statusPath, 'utf-8'));
+        if (existing.startedAt) startedAt = existing.startedAt;
+    }
+} catch (_) {}
+
+// gitnexus requires Node >=20
+const nodeMajor = parseInt(process.version.slice(1).split('.')[0], 10);
+if (nodeMajor < 20) {
+    try {
+        fs.writeFileSync(statusPath, JSON.stringify({
+            status: 'error',
+            startedAt,
+            completedAt: new Date().toISOString(),
+            error: `Node.js version >=20 required (current: ${process.version})`,
+        }, null, 2));
+    } catch (_) {}
+    process.exit(0);
+}
+
+// Status path and log path already defined above
+
+const logStream = fs.createWriteStream(logPath, { flags: 'w' });
+
+// On Windows use shell:true — avoids EINVAL when spawning .cmd scripts
+const isWin = process.platform === 'win32';
+
+const hasGlobalGitNexus = commandExists('gitnexus');
+const cmd = hasGlobalGitNexus ? 'gitnexus' : 'npx';
+const args = hasGlobalGitNexus ? ['analyze'] : ['-y', 'gitnexus@latest', 'analyze'];
+
+const child = spawn(cmd, args, {
+    cwd: projectDir,
+    shell: isWin,
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+});
+
+child.stdout.pipe(logStream);
+child.stderr.pipe(logStream);
+
+child.on('close', (code) => {
+    const status = code === 0
+        ? { status: 'done',  startedAt, completedAt: new Date().toISOString() }
+        : { status: 'error', startedAt, completedAt: new Date().toISOString(), exitCode: code };
+    try {
+        fs.writeFileSync(statusPath, JSON.stringify(status, null, 2));
+    } catch (_) {}
+});
+
+child.on('error', (err) => {
+    try {
+        fs.writeFileSync(statusPath, JSON.stringify({
+            status: 'error',
+            startedAt,
+            completedAt: new Date().toISOString(),
+            exitCode: null,
+            error: err.message,
+        }, null, 2));
+    } catch (_) {}
+});

package/scripts/guide.js

@@ -1,3 +1,5 @@
+const fs = require('fs');
+const path = require('path');
 const chalk = require('chalk');
 
 // ──────────────────────────────────────────────────────────────
@@ -40,56 +42,42 @@ function showHeader() {
 // ──────────────────────────────────────────────────────────────
 
 function showFlow() {
-    console.log(chalk.bold.cyan('  📐 ARCHITECTURE & FLOW\n'));
+    console.log(chalk.bold.cyan('  ⛩️  WORKFLOW OVERVIEW (AIFLOW.md)\n'));
 
-    console.log(chalk.gray('  ┌──────────────────────────────────────────────────────┐'));
-    console.log(chalk.gray('  │') + chalk.bold.yellow('  TECH LEAD (One-time setup)') + chalk.gray('                         │'));
-    console.log(chalk.gray('  │') + chalk.white('  1. Configure custom/rules/, custom/templates/') + chalk.gray('        │'));
-    console.log(chalk.gray('  │') + chalk.white('  2. npm publish  →  developer: npm install -g pkg') + chalk.gray('    │'));
-    console.log(chalk.gray('  └─────────────────────────┬────────────────────────────┘'));
-    console.log(chalk.gray('                            │'));
-    console.log(chalk.gray('              ┌─────────────▼──────────────┐'));
-    console.log(chalk.gray('              │') + chalk.bold.green('    aiflow init') + chalk.gray('                │'));
-    console.log(chalk.gray('              │') + chalk.white('  --framework spring-boot') + chalk.gray('      │'));
-    console.log(chalk.gray('              │') + chalk.white('  --adapter backlog') + chalk.gray('            │'));
-    console.log(chalk.gray('              └─────────────┬──────────────┘'));
-    console.log(chalk.gray('                            │ generates'));
-    console.log(chalk.gray('              ┌─────────────▼──────────────────────────┐'));
-    console.log(chalk.gray('              │') + chalk.white('  .claude/skills/    ← superpowers + custom') + chalk.gray(' │'));
-    console.log(chalk.gray('              │') + chalk.white('  .claude/hooks/     ← SessionStart hook') + chalk.gray('    │'));
-    console.log(chalk.gray('              │') + chalk.white('  .rules/            ← team coding rules') + chalk.gray('    │'));
-    console.log(chalk.gray('              │') + chalk.white('  CLAUDE.md          ← framework AI prompt') + chalk.gray('  │'));
-    console.log(chalk.gray('              │') + chalk.white('  .mcp.json          ← MCP adapter config') + chalk.gray('   │'));
-    console.log(chalk.gray('              └─────────────┬──────────────────────────┘'));
-    console.log(chalk.gray('                            │'));
-    console.log(chalk.gray('         ┌──────────────────▼───────────────────┐'));
-    console.log(chalk.gray('         │') + chalk.bold.green('  Developer Workflow (per task)') + chalk.gray('         │'));
-    console.log(chalk.gray('         │') + chalk.white('                                        │'));
-    console.log(chalk.gray('         │') + chalk.cyan('  1. aiflow use PROJ-33') + chalk.gray('                 │'));
-    console.log(chalk.gray('         │') + chalk.gray('     └─ pull title, desc, comments from  │'));
-    console.log(chalk.gray('         │') + chalk.gray('        Backlog/Jira → current.json      │'));
-    console.log(chalk.gray('         │') + chalk.white('                                        │'));
-    console.log(chalk.gray('         │') + chalk.cyan('  2. aiflow prompt bug-fix') + chalk.gray('              │'));
-    console.log(chalk.gray('         │') + chalk.gray('     └─ generate AI prompt from context  │'));
-    console.log(chalk.gray('         │') + chalk.gray('        + team rules → paste into Claude │'));
-    console.log(chalk.gray('         │') + chalk.white('                                        │'));
-    console.log(chalk.gray('         │') + chalk.cyan('  3. claude (open Claude terminal)') + chalk.gray('       │'));
-    console.log(chalk.gray('         │') + chalk.gray('     └─ "Fix bug PROJ-33" (1 line)       │'));
-    console.log(chalk.gray('         └──────────────────┬───────────────────┘'));
-    console.log(chalk.gray('                            │'));
-    console.log(chalk.gray('         ┌──────────────────▼───────────────────┐'));
-    console.log(chalk.gray('         │') + chalk.bold.magenta('  Claude AI (automatic)') + chalk.gray('                │'));
-    console.log(chalk.gray('         │') + chalk.white('                                        │'));
-    console.log(chalk.gray('         │') + chalk.gray('  SessionStart hook injected superpowers  │'));
-    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
-    console.log(chalk.gray('         │') + chalk.gray('  Read CLAUDE.md (framework rules)       │'));
-    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
-    console.log(chalk.gray('         │') + chalk.gray('  Read context/current.json (ticket)     │'));
-    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
-    console.log(chalk.gray('         │') + chalk.gray('  Auto-detect task type → select skill   │'));
-    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
-    console.log(chalk.gray('         │') + chalk.gray('  Implement with team rules              │'));
-    console.log(chalk.gray('         └────────────────────────────────────────┘'));
+    try {
+        const aiflowPath = path.join(__dirname, '../docs/common/AIFLOW.md');
+        if (!fs.existsSync(aiflowPath)) {
+            console.log(chalk.red('    Error: AIFLOW.md not found.'));
+            return;
+        }
+
+        const content = fs.readFileSync(aiflowPath, 'utf8');
+        const lines = content.split('\n');
+        
+        let inSection = false;
+        let sectionLines = [];
+
+        for (const line of lines) {
+            if (line.trim() === '## Workflow Overview') {
+                inSection = true;
+                continue;
+            }
+            if (inSection) {
+                if (line.startsWith('## ') || line.trim() === '---') {
+                    break;
+                }
+                sectionLines.push(line);
+            }
+        }
+
+        if (sectionLines.length > 0) {
+            console.log(chalk.white(sectionLines.join('\n')));
+        } else {
+            console.log(chalk.yellow('    (Workflow Overview section not found in AIFLOW.md)'));
+        }
+    } catch (error) {
+        console.log(chalk.red('    Error reading AIFLOW.md: ' + error.message));
+    }
     console.log();
 }
 
@@ -159,11 +147,14 @@ function showCommands() {
             items: [
                 ['aiflow init', '--framework <fw> --adapter <ad>', 'Initialize project'],
                 ['aiflow init', '--env <tools>', 'AI tools: cursor,gemini,copilot'],
-                ['aiflow init', '--with-rtk | --no-rtk', 'Enable/disable RTK compression'],
-                ['aiflow doctor', '', 'Check setup health'],
+                ['aiflow init', '--with-rtk | --no-rtk', 'RTK bash compression (60–90% saving)'],
+                // ['aiflow init', '--with-gitnexus', 'GitNexus code intelligence (waits for index)'],
+                // ['aiflow init', '--with-gitnexus --no-wait', 'GitNexus: index in background'],
+                ['aiflow doctor', '', 'Check setup health + token savings status'],
                 ['aiflow doctor', '--verbose', 'Detailed health check output'],
                 ['aiflow update', '', 'Update to the latest version'],
                 ['aiflow update', '--force', 'Force update even if already latest'],
+                ['aiflow sync-skills', '', 'Manually sync AI Instruction files'],
                 ['aiflow remove', '', 'Remove ai-flow-kit from project'],
                 ['aiflow remove', '--version <ver>', 'Remove a cached version'],
                 ['aiflow remove', '--global', 'Uninstall global package'],

package/scripts/hooks/session-start.js

@@ -41,7 +41,37 @@ try {
     // Context missing or invalid — continue without it
 }
 
-// ── 3. Combine and output ──────────────────────────────────────
+// ── 3. Check GitNexus background indexing status ───────────────
+const GITNEXUS_STALE_MS = 3 * 60 * 60 * 1000; // 3 hours
+const gitNexusStatusPath = path.join(projectRoot, '.aiflow', 'gitnexus-status.json');
+try {
+    if (fs.existsSync(gitNexusStatusPath)) {
+        const gn = JSON.parse(fs.readFileSync(gitNexusStatusPath, 'utf-8'));
+        if (!gn.notified) {
+            // Detect stale "running" — process was killed without updating status
+            if (gn.status === 'running' && gn.startedAt) {
+                const age = Date.now() - new Date(gn.startedAt).getTime();
+                if (age > GITNEXUS_STALE_MS) {
+                    gn.status = 'error';
+                    gn.error = 'timed out — process may have been killed or ran out of memory';
+                }
+            }
+            if (gn.status === 'done') {
+                process.stderr.write('[aiflow] ✓ GitNexus indexing complete — code intelligence tools are ready.\n');
+            } else if (gn.status === 'error') {
+                const detail = gn.error ? ` (${gn.error})` : gn.exitCode != null ? ` (exit ${gn.exitCode})` : '';
+                process.stderr.write(`[aiflow] ✗ GitNexus indexing failed${detail}.\n`);
+                // process.stderr.write('[aiflow]   Retry: aiflow init --with-gitnexus\n');
+            }
+            if (gn.status === 'done' || gn.status === 'error') {
+                gn.notified = true;
+                fs.writeFileSync(gitNexusStatusPath, JSON.stringify(gn, null, 2));
+            }
+        }
+    }
+} catch (_) {}
+
+// ── 4. Combine and output ──────────────────────────────────────
 const parts = [];
 
 if (skillContent) {
@@ -222,12 +252,12 @@ function buildModeInstruction(mode, gate) {
         ],
         3: [
             '**MODE: fast** — Gate 3 fast track:',
+            '- INVOKE `tdd-lean` skill (NOT superpowers:test-driven-development)',
+            '- tdd-lean uses Batch Red-Green-Refactor: 2–3 test runs total, never per-test',
+            '- Test Output Discipline: keep only summary line after each run, discard stack traces',
             '- DO NOT use `superpowers:subagent-driven-development`',
             '- DO NOT spawn Spec Reviewer or Code Quality Reviewer subagents',
-            '- Implement ALL tasks directly in this session',
-            '- Write tests and implementation in the same pass per task',
-            '- Run the test suite ONCE at the end of all tasks (not after each step)',
-            '- If tests fail: fix inline, do not spawn a subagent',
+            '- Call `aiflow checkpoint` at each milestone (tests-written, code-done, tests-pass)',
         ],
         4: [
             '**MODE: fast** — Gate 4 fast track:',

package/scripts/hooks/session-stop.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * SessionStop hook for ai-flow-kit
+ * Reads checkpoints.json for the active task and prints a token usage summary.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { record } = require('../telemetry/record');
+
+record('session.stop');
+
+const projectRoot  = path.resolve(__dirname, '..', '..');
+const contextFile  = path.join(projectRoot, '.aiflow', 'context', 'current.json');
+const tasksDir     = path.join(projectRoot, '.aiflow', 'tasks');
+
+const GATE_LABELS = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+
+try {
+    if (!fs.existsSync(contextFile)) process.exit(0);
+    const ctx = JSON.parse(fs.readFileSync(contextFile, 'utf-8'));
+    const ticketId = ctx && ctx.taskId;
+    if (!ticketId) process.exit(0);
+
+    const checkpointPath = path.join(tasksDir, ticketId, 'checkpoints.json');
+    if (!fs.existsSync(checkpointPath)) process.exit(0);
+
+    const data = JSON.parse(fs.readFileSync(checkpointPath, 'utf-8'));
+    const checkpoints = data.checkpoints || [];
+    if (checkpoints.length === 0) process.exit(0);
+
+    // Aggregate latest token value per gate
+    const gateTokens = {};
+    for (const cp of checkpoints) {
+        const g = cp.gate;
+        if (!gateTokens[g] || cp.tokens > gateTokens[g]) {
+            gateTokens[g] = cp.tokens;
+        }
+    }
+
+    const gates = Object.keys(gateTokens).sort();
+    const total  = gates.reduce((sum, g) => sum + gateTokens[g], 0);
+
+    process.stderr.write('\n[aiflow] Token usage this session:\n');
+    for (const g of gates) {
+        const label   = GATE_LABELS[parseInt(g)] || `Gate ${g}`;
+        const t       = gateTokens[g];
+        const bar     = '█'.repeat(Math.round((t / total) * 20)).padEnd(20, '░');
+        const pct     = Math.round((t / total) * 100);
+        process.stderr.write(`[aiflow]   Gate ${g}  ${label.padEnd(8)}  ~${t.toLocaleString().padStart(6)}  ${bar}  ${pct}%\n`);
+    }
+    process.stderr.write(`[aiflow]   Total estimated: ~${total.toLocaleString()} tokens\n\n`);
+} catch (_) {}
+
+process.exit(0);