@relipa/ai-flow-kit 0.1.0-beta.0 → 0.1.1-beta.0

package/scripts/use.js

@@ -1,1162 +1,1162 @@
-const fs = require("fs-extra");
-const path = require("path");
-const os = require("os");
-const chalk = require("chalk");
-const https = require("https");
-const { select, input } = require("@inquirer/prompts");
-
-const PROJECT_DIR = process.cwd();
-const AIFLOW_DIR = path.join(PROJECT_DIR, ".aiflow");
-const STATE_FILE = path.join(AIFLOW_DIR, "state.json");
-const CONTEXT_DIR = path.join(PROJECT_DIR, ".aiflow", "context");
-
-// ──────────────────────────────────────────────────────────────
-// Entry point
-// ──────────────────────────────────────────────────────────────
-
-const useCommand = async function use(targets, options = {}) {
-  // Normalize: accept string (legacy) or array (new multi-target)
-  const targetList = Array.isArray(targets) ? targets.filter(Boolean) : (targets ? [targets] : []);
-  const primaryTarget = targetList[0] || null;
-  const supplementaryTargets = targetList.slice(1);
-
-  if (!(await fs.pathExists(STATE_FILE))) {
-    console.log(
-      chalk.red("Project is not initialized. Run `aiflow init` first."),
-    );
-    return;
-  }
-
-  // ── GitNexus index notification (all AI tools see this) ──────
-  await checkGitNexusIndexStatus();
-
-  // ── Manual entry ──
-  if (options.manual) {
-    return await manualContext();
-  }
-
-  // ── Load from local file ──
-  if (options.file) {
-    return await loadFromFile(options.file, options);
-  }
-
-  // ── No target → version switcher ──
-  if (!primaryTarget) {
-    return await switchVersion();
-  }
-
-  // ── Detect target type and dispatch ──
-  if (isVersion(primaryTarget)) {
-    return await switchVersion(primaryTarget);
-  }
-
-  if (isTicketId(primaryTarget)) {
-    const adapter = await resolveTicketAdapter();
-    if (adapter === "jira") await loadFromJira(primaryTarget, options);
-    else await loadFromBacklog(primaryTarget, options);
-    return await enrichWithSupplementary(supplementaryTargets);
-  }
-
-  if (isBacklogUrl(primaryTarget)) {
-    const id = extractBacklogId(primaryTarget);
-    await loadFromBacklog(id, options);
-    return await enrichWithSupplementary(supplementaryTargets);
-  }
-
-  // ── Fallback: try Backlog then manual ──
-  console.log(chalk.yellow(`Cannot detect format for: ${primaryTarget}`));
-  console.log(
-    chalk.gray("Supported: PROJ-33, APP-123, version number, --manual"),
-  );
-  return await manualContext();
-};
-
-// ──────────────────────────────────────────────────────────────
-// Detectors
-// ──────────────────────────────────────────────────────────────
-
-function isVersion(s) {
-  return /^\d+\.\d+\.\d+$/.test(s);
-}
-
-/** Both Backlog and Jira use the same PROJECT-NUMBER format. */
-function isTicketId(s) {
-  return /^[A-Z][A-Z0-9_]+-\d+$/.test(s);
-}
-
-/**
- * Determine which adapter to use for a ticket ID based on configured adapters
- * in state.json. Falls back to backlog if both or neither are configured.
- */
-async function resolveTicketAdapter() {
-  try {
-    if (await fs.pathExists(STATE_FILE)) {
-      const state = await fs.readJson(STATE_FILE);
-      const adapters = state.adapters || [];
-      if (adapters.includes("jira") && !adapters.includes("backlog")) {
-        return "jira";
-      }
-    }
-  } catch (_) {
-    /* ignore */
-  }
-  return "backlog";
-}
-
-function isBacklogUrl(s) {
-  return s.includes("backlog.com/view/") || s.includes("backlogtool.com/view/");
-}
-
-function extractBacklogId(url) {
-  const match = url.match(/\/view\/([A-Z][A-Z0-9_]+-\d+)/);
-  return match ? match[1] : null;
-}
-
-// ──────────────────────────────────────────────────────────────
-// Version switcher (original behavior)
-// ──────────────────────────────────────────────────────────────
-
-async function switchVersion(versionReq) {
-  const versionsDir = path.join(AIFLOW_DIR, "versions");
-  if (!(await fs.pathExists(versionsDir))) {
-    console.log(chalk.red("No versions directory found."));
-    return;
-  }
-
-  const available = await fs.readdir(versionsDir);
-  if (!available.length) {
-    console.log(chalk.red("No installed versions found."));
-    return;
-  }
-
-  let targetVersion = versionReq;
-  if (!targetVersion) {
-    targetVersion = await select({
-      message: "Select version to use:",
-      choices: available.map((v) => ({ name: `v${v}`, value: v })),
-    });
-  }
-
-  if (!available.includes(targetVersion)) {
-    console.log(chalk.red(`Version v${targetVersion} is not installed.`));
-    return;
-  }
-
-  console.log(chalk.blue(`Switching to v${targetVersion}...`));
-  const versionDir = path.join(versionsDir, targetVersion);
-
-  const claudeDir = path.join(PROJECT_DIR, ".claude");
-  await fs.emptyDir(claudeDir);
-  await fs.copy(
-    path.join(versionDir, "skills"),
-    path.join(claudeDir, "skills"),
-    { overwrite: true },
-  );
-
-  const rulesDir = path.join(PROJECT_DIR, ".rules");
-  await fs.emptyDir(rulesDir);
-  await fs.copy(path.join(versionDir, "rules"), rulesDir, { overwrite: true });
-
-  const state = await fs.readJson(STATE_FILE);
-  state.current_version = targetVersion;
-  await fs.writeJson(STATE_FILE, state);
-
-  console.log(chalk.green(`✓ Switched to v${targetVersion}.`));
-}
-
-// ──────────────────────────────────────────────────────────────
-// Backlog context loader
-// ──────────────────────────────────────────────────────────────
-
-async function loadFromBacklog(issueKey, options = {}) {
-  const creds = await loadCredentials();
-  const apiKey = process.env.BACKLOG_API_KEY || creds.BACKLOG_API_KEY;
-  const spaceKey =
-    process.env.BACKLOG_SPACE_KEY ||
-    creds.BACKLOG_SPACE_KEY ||
-    process.env.BACKLOG_DOMAIN ||
-    creds.BACKLOG_DOMAIN;
-
-  if (!apiKey || !spaceKey) {
-    console.log(chalk.yellow("⚠ Backlog credentials not set."));
-    console.log(chalk.gray("Run: aiflow init --adapter backlog"));
-    console.log(chalk.gray("Or set environment variables:"));
-    console.log(chalk.gray("  BACKLOG_API_KEY=your-api-key"));
-    console.log(chalk.gray("  BACKLOG_SPACE_KEY=your-space (e.g. mycompany)"));
-    console.log(chalk.gray("\nFalling back to manual entry...\n"));
-    return await manualContext(issueKey);
-  }
-
-  // spaceKey can be full domain (mycompany.backlog.com) or just the space (mycompany)
-  const domain = spaceKey.includes(".") ? spaceKey : `${spaceKey}.backlog.com`;
-
-  console.log(chalk.blue(`Fetching context from Backlog: ${issueKey}...`));
-
-  try {
-    // Default: description only. Comments loaded only when explicitly requested.
-    const loadComments =
-      options.coms ||
-      options.withComs ||
-      options.withComments ||
-      options["with-comments"] ||
-      options.with_comments ||
-      options.cid != null ||
-      options.commentId != null ||
-      options["comment-id"] != null ||
-      options.clast != null ||
-      options.commentsLast != null ||
-      options.cfrom != null ||
-      options.commentsFrom != null ||
-      options.cto != null ||
-      options.commentsTo != null ||
-      options["comments-to"] != null;
-    
-    if (loadComments) {
-      console.log(chalk.gray("  ℹ Comments requested..."));
-    }
-    const [issue, rawComments] = await Promise.all([
-      fetchBacklogIssue(domain, apiKey, issueKey),
-      loadComments
-        ? fetchBacklogComments(domain, apiKey, issueKey)
-        : Promise.resolve([]),
-    ]);
-
-    const comments = filterComments(rawComments, options);
-    if (loadComments) {
-      console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
-    }
-    const context = buildContextFromBacklog(issue, comments, issueKey, domain);
-    context.mode = options.full ? "full" : "fast";
-    await saveContext(context, options.save);
-    printContextSummary(context);
-    await suggestNextStep();
-  } catch (err) {
-    console.log(chalk.yellow(`⚠ Could not fetch from Backlog: ${err.message}`));
-    console.log(chalk.gray("Falling back to manual entry...\n"));
-    await manualContext(issueKey);
-  }
-}
-
-/**
- * Filter comments array based on CLI options:
- *   --no-comments      → empty array (already handled upstream, but safe here too)
- *   --comments-last N  → last N comments
- *   --comments-from N  → comments starting at index N (0-based)
- *   (default)          → all comments
- */
-function filterComments(comments, options = {}) {
-  if (!comments || !comments.length) return [];
-
-  let result = [...comments];
-
-  // 1. Filter by specific ID if provided
-  const targetId = options.cid || options.commentId || options["comment-id"];
-  if (targetId) {
-    result = result.filter((c) => String(c.id) === String(targetId));
-  }
-
-  // 2. Filter by starting ID (from)
-  const fromId = options.cfrom || options.commentsFrom || options["comments-from"];
-  if (fromId) {
-    result = result.filter((c) => Number(c.id) >= Number(fromId));
-  }
-
-  // 3. Filter by ending ID (to)
-  const toId = options.cto || options.commentsTo || options["comments-to"];
-  if (toId) {
-    result = result.filter((c) => Number(c.id) <= Number(toId));
-  }
-
-  // 4. Filter by last N comments (if not using specific ID/range filters)
-  const lastN = options.clast || options.commentsLast;
-  if (lastN != null && !targetId && !fromId && !toId) {
-    const n = Math.max(1, lastN);
-    return result.slice(-n);
-  }
-
-  return result;
-}
-
-/**
- * Generic Backlog GET helper
- */
-function backlogGet(url) {
-  return new Promise((resolve, reject) => {
-    https
-      .get(url, (res) => {
-        let data = "";
-        res.on("data", (chunk) => (data += chunk));
-        res.on("end", () => {
-          if (res.statusCode !== 200) {
-            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
-            return;
-          }
-          try {
-            resolve(JSON.parse(data));
-          } catch (e) {
-            reject(new Error("Invalid JSON response from Backlog"));
-          }
-        });
-      })
-      .on("error", reject);
-  });
-}
-
-/**
- * Fetch issue detail from Backlog REST API
- */
-function fetchBacklogIssue(domain, apiKey, issueKey) {
-  return backlogGet(
-    `https://${domain}/api/v2/issues/${issueKey}?apiKey=${apiKey}`,
-  );
-}
-
-/**
- * Fetch ALL comments of an issue from Backlog REST API.
- * Uses minId for pagination because 'offset' is not supported for comments.
- */
-async function fetchBacklogComments(domain, apiKey, issueKey) {
-  const all = [];
-  let minId = null;
-  try {
-    while (true) {
-      let url = `https://${domain}/api/v2/issues/${issueKey}/comments?apiKey=${apiKey}&count=100&order=asc`;
-      if (minId) {
-        url += `&minId=${minId}`;
-      }
-      
-      const batch = await backlogGet(url);
-      if (!batch || batch.length === 0) break;
-      
-      all.push(...batch);
-      if (batch.length < 100) break;
-      
-      // Use the last ID as minId for the next batch
-      minId = batch[batch.length - 1].id;
-    }
-  } catch (err) {
-    console.log(
-      chalk.yellow(`  ⚠ Warning: Could not fetch comments: ${err.message}`),
-    );
-  }
-  return all;
-}
-
-/**
- * Transform Backlog API response + comments to internal context format
- */
-function buildContextFromBacklog(issue, comments, issueKey, domain) {
-  const type = detectTaskType(issue);
-
-  // Format comments into readable text for AI context
-  const formattedComments = (comments || [])
-    .map((c) => {
-      // Backlog comments can have text in 'content' or be just changelogs
-      const text = c.content || "";
-      if (!text.trim()) return null;
-
-      const author = c.createdUser?.name || "Unknown";
-      const date = c.created
-        ? new Date(c.created).toLocaleDateString("vi-VN")
-        : "";
-      return `[${author} - ${date}]\n${text.trim()}`;
-    })
-    .filter(Boolean);
-
-  const allText = [
-    issue.description || "",
-    ...formattedComments.map((c) => c),
-  ].join("\n");
-
-  return {
-    taskId: issueKey,
-    taskType: type,
-    title: issue.summary || "",
-    description: issue.description || "",
-    status: issue.status?.name || "Unknown",
-    priority: issue.priority?.name || "Unknown",
-    assignee: issue.assignee?.name || "Unassigned",
-
-    // Comments from all participants
-    comments: formattedComments,
-    commentCount: formattedComments.length,
-
-    // Parse checklist-style acceptance criteria from description
-    acceptanceCriteria: extractCriteria(issue.description || ""),
-
-    // Related files mentioned anywhere in ticket
-    context: {
-      files: extractFiles(allText),
-      mentionedServices: [],
-      relatedTickets: extractRelatedTickets(allText),
-    },
-
-    metadata: {
-      created: issue.created,
-      updated: issue.updated,
-      loadedFrom: "backlog",
-      adapter: "backlog",
-      sourceUrl: `https://${domain}/view/${issueKey}`,
-    },
-  };
-}
-
-// ──────────────────────────────────────────────────────────────
-// Jira context loader
-// ──────────────────────────────────────────────────────────────
-
-async function loadFromJira(issueKey, options = {}) {
-  const creds = await loadCredentials();
-  const apiToken = process.env.JIRA_API_TOKEN || creds.JIRA_API_TOKEN;
-  const email = process.env.JIRA_EMAIL || creds.JIRA_EMAIL;
-  const domain = process.env.JIRA_DOMAIN || creds.JIRA_DOMAIN;
-
-  if (!apiToken || !email || !domain) {
-    console.log(chalk.yellow("⚠ Jira credentials not set."));
-    console.log(chalk.gray("Run: aiflow init --adapter jira"));
-    console.log(
-      chalk.gray(
-        "Or set environment variables: JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN",
-      ),
-    );
-    console.log(chalk.gray("\nFalling back to manual entry...\n"));
-    return await manualContext(issueKey);
-  }
-
-  console.log(chalk.blue(`Fetching context from Jira: ${issueKey}...`));
-
-  try {
-    const loadComments =
-      options.coms ||
-      options.withComs ||
-      options.withComments ||
-      options["with-comments"] ||
-      options.with_comments ||
-      options.cid != null ||
-      options.commentId != null ||
-      options["comment-id"] != null ||
-      options.clast != null ||
-      options.commentsLast != null ||
-      options.cfrom != null ||
-      options.commentsFrom != null ||
-      options.cto != null ||
-      options.commentsTo != null ||
-      options["comments-to"] != null;
-    
-    if (loadComments) {
-      console.log(chalk.gray("  ℹ Comments requested..."));
-    }
-    const [issue, rawComments] = await Promise.all([
-      fetchJiraIssue(domain, email, apiToken, issueKey),
-      loadComments
-        ? fetchJiraComments(domain, email, apiToken, issueKey)
-        : Promise.resolve([]),
-    ]);
-
-    const comments = filterComments(rawComments, options);
-    if (loadComments) {
-      console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
-    }
-    const context = buildContextFromJira(issue, comments, issueKey, domain);
-    context.mode = options.full ? "full" : "fast";
-    await saveContext(context, options.save);
-    printContextSummary(context);
-    await suggestNextStep();
-  } catch (err) {
-    console.log(chalk.yellow(`⚠ Could not fetch from Jira: ${err.message}`));
-    console.log(chalk.gray("Falling back to manual entry...\n"));
-    await manualContext(issueKey);
-  }
-}
-
-function fetchJiraIssue(domain, email, apiToken, issueKey) {
-  return new Promise((resolve, reject) => {
-    const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
-    const url = `https://${domain}.atlassian.net/rest/api/3/issue/${issueKey}`;
-    const options = {
-      headers: {
-        Authorization: `Basic ${auth}`,
-        Accept: "application/json",
-      },
-    };
-
-    https
-      .get(url, options, (res) => {
-        let data = "";
-        res.on("data", (chunk) => (data += chunk));
-        res.on("end", () => {
-          if (res.statusCode !== 200) {
-            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
-            return;
-          }
-          try {
-            resolve(JSON.parse(data));
-          } catch (e) {
-            reject(new Error("Invalid JSON response from Jira"));
-          }
-        });
-      })
-      .on("error", reject);
-  });
-}
-
-/**
- * Fetch ALL comments of an issue from Jira REST API.
- */
-async function fetchJiraComments(domain, email, apiToken, issueKey) {
-  return new Promise((resolve, reject) => {
-    const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
-    const url = `https://${domain}.atlassian.net/rest/api/3/issue/${issueKey}/comment`;
-    const options = {
-      headers: {
-        Authorization: `Basic ${auth}`,
-        Accept: "application/json",
-      },
-    };
-
-    https
-      .get(url, options, (res) => {
-        let data = "";
-        res.on("data", (chunk) => (data += chunk));
-        res.on("end", () => {
-          if (res.statusCode !== 200) {
-            // Comments are optional, but log if we failed
-            console.log(
-              chalk.yellow(
-                `  ⚠ Warning: Jira comments API returned ${res.statusCode}`,
-              ),
-            );
-            resolve([]);
-            return;
-          }
-          try {
-            const json = JSON.parse(data);
-            resolve(json.comments || []);
-          } catch (e) {
-            resolve([]);
-          }
-        });
-      })
-      .on("error", () => resolve([]));
-  });
-}
-
-function buildContextFromJira(issue, comments, issueKey, domain) {
-  const fields = issue.fields || {};
-  const type = detectTaskTypeFromString(fields.issuetype?.name || "");
-
-  // Format comments for Jira (v3 uses ADF format for body)
-  const formattedComments = (comments || [])
-    .map((c) => {
-      const author = c.author?.displayName || "Unknown";
-      const date = c.created
-        ? new Date(c.created).toLocaleDateString("vi-VN")
-        : "";
-      const body =
-        c.body?.content
-          ?.map(
-            (block) => block.content?.map((inner) => inner.text).join("") || "",
-          )
-          .join("\n") || "";
-      return body.trim() ? `[${author} - ${date}]\n${body.trim()}` : null;
-    })
-    .filter(Boolean);
-
-  return {
-    taskId: issueKey,
-    taskType: type,
-    title: fields.summary || "",
-    description:
-      fields.description?.content
-        ?.map((block) => block.content?.map((c) => c.text).join("") || "")
-        .join("\n") || "",
-    status: fields.status?.name || "Unknown",
-    priority: fields.priority?.name || "Unknown",
-    assignee: fields.assignee?.displayName || "Unassigned",
-
-    // Comments
-    comments: formattedComments,
-    commentCount: formattedComments.length,
-
-    acceptanceCriteria: extractCriteria(fields.description?.toString() || ""),
-    context: {
-      files: [],
-      relatedTickets: [],
-    },
-    metadata: {
-      created: fields.created,
-      updated: fields.updated,
-      loadedFrom: "jira",
-      adapter: "jira",
-      sourceUrl: `https://${domain}.atlassian.net/browse/${issueKey}`,
-    },
-  };
-}
-
-// ──────────────────────────────────────────────────────────────
-// Manual context entry
-// ──────────────────────────────────────────────────────────────
-
-async function manualContext(prefillId = "") {
-  // Load existing context for pre-fill (Edit mode)
-  let existing = {};
-  const currentPath = path.join(CONTEXT_DIR, "current.json");
-  if (await fs.pathExists(currentPath)) {
-    existing = await fs.readJson(currentPath).catch(() => ({}));
-  }
-
-  const isEdit = !!existing.taskId;
-  if (isEdit) {
-    console.log(chalk.cyan("\nEdit Context\n"));
-    console.log(
-      chalk.gray("Press Enter to keep existing value shown in [brackets]\n"),
-    );
-  } else {
-    console.log(chalk.cyan("\nManual Context Entry\n"));
-  }
-
-  // Ticket ID
-  const defaultId = prefillId || existing.taskId || "";
-  const idHint = defaultId ? chalk.gray(` [${defaultId}]`) : "";
-  const idInput = await input({
-    message: `Ticket ID (e.g. PROJ-33)${idHint}:`,
-    default: "",
-  });
-  const taskId = idInput.trim() || defaultId;
-
-  // Title
-  const defaultTitle = existing.title || "";
-  const titlePreview =
-    defaultTitle.length > 50
-      ? defaultTitle.substring(0, 50) + "…"
-      : defaultTitle;
-  const titleHint = defaultTitle ? chalk.gray(` [${titlePreview}]`) : "";
-  const titleInput = await input({
-    message: `Title${titleHint}:`,
-    default: "",
-  });
-  const title = titleInput.trim() || defaultTitle;
-
-  // Description
-  const defaultDesc = existing.description || "";
-  const descPreview =
-    defaultDesc.length > 60 ? defaultDesc.substring(0, 60) + "…" : defaultDesc;
-  const descHint = defaultDesc ? chalk.gray(` [${descPreview}]`) : "";
-  const descInput = await input({
-    message: `Description (brief)${descHint}:`,
-    default: "",
-  });
-  const description = descInput.trim() || defaultDesc;
-
-  // Task type — pre-select existing value if available
-  const taskType = await select({
-    message: "Task type:",
-    choices: [
-      { name: "🐛 Bug Fix", value: "bug-fix" },
-      { name: "✨ Feature", value: "feature" },
-      { name: "🔍 Investigation", value: "investigation" },
-      { name: "♻️  Refactor", value: "refactor" },
-      { name: "📊 Impact Analysis", value: "impact-analysis" },
-      { name: "📖 Documentation", value: "documentation" },
-    ],
-    default: existing.taskType || undefined,
-  });
-
-  const context = {
-    taskId,
-    taskType,
-    title,
-    description,
-    status: existing.status || "In Progress",
-    mode: existing.mode || "auto",
-    acceptanceCriteria: existing.acceptanceCriteria || [],
-    context: existing.context || { files: [], relatedTickets: [] },
-    metadata: {
-      created: existing.metadata?.created || new Date().toISOString(),
-      updated: new Date().toISOString(),
-      loadedFrom: "manual",
-      adapter: "manual",
-    },
-  };
-
-  await saveContext(context);
-  printContextSummary(context);
-  await suggestNextStep();
-}
-
-// ──────────────────────────────────────────────────────────────
-// Load from JSON file
-// ──────────────────────────────────────────────────────────────
-
-async function loadFromFile(filePath, options = {}) {
-  if (!(await fs.pathExists(filePath))) {
-    console.log(chalk.red(`File not found: ${filePath}`));
-    return;
-  }
-
-  const raw = await fs.readFile(filePath, "utf-8");
-  let context;
-
-  // Try JSON first; fall back to plain-text auto-detection
-  try {
-    context = JSON.parse(raw);
-  } catch (_) {
-    console.log(
-      chalk.gray(
-        "  File is not JSON — auto-detecting task info from content...",
-      ),
-    );
-    context = buildContextFromPlainText(raw, filePath);
-  }
-
-  context.mode = options.full ? "full" : "fast";
-
-  // Prompt for task type
-  context.taskType = await select({
-    message: "Task type:",
-    choices: [
-      { name: "🐛 Bug Fix", value: "bug-fix" },
-      { name: "✨ Feature", value: "feature" },
-      { name: "🔍 Investigation", value: "investigation" },
-      { name: "♻️  Refactor", value: "refactor" },
-      { name: "📊 Impact Analysis", value: "impact-analysis" },
-      { name: "📖 Documentation", value: "documentation" },
-    ],
-    default: context.taskType || "feature",
-  });
-
-  await saveContext(context, options.save);
-  printContextSummary(context);
-  await suggestNextStep();
-}
-
-/**
- * Build a minimal context object from arbitrary plain-text file content.
- * Tries to detect ticket ID (e.g. PROJ-33, APP-123) and a title from the first non-blank line.
- */
-function buildContextFromPlainText(text, filePath = "") {
-  // Detect ticket ID: first PROJ-123 style token anywhere in the text
-  const idMatch = text.match(/\b([A-Z][A-Z0-9_]+-\d+)\b/);
-
-  let taskId;
-  if (idMatch) {
-    taskId = idMatch[1];
-  } else {
-    const fileNameOnly = filePath
-      ? path.basename(filePath, path.extname(filePath))
-      : "";
-    const cleanWords = fileNameOnly
-      .replace(/[^a-zA-Z0-9]/g, " ")
-      .split(/\s+/)
-      .filter(Boolean)
-      .slice(0, 5)
-      .join("-")
-      .toUpperCase();
-    const prefix = cleanWords ? `TASK-${cleanWords}-` : "TASK-";
-    taskId = `${prefix}${Date.now()}`;
-  }
-
-  // Title: use full filename if available, otherwise first non-blank line
-  const fullFileName = filePath ? path.basename(filePath) : "";
-  const lines = text
-    .split(/\r?\n/)
-    .map((l) => l.trim())
-    .filter(Boolean);
-  const titleLine = fullFileName || lines.find((l) => l.length > 3) || taskId;
-  const title = titleLine.substring(0, 120);
-
-  // Task type detection from text
-  const taskType = detectTaskTypeFromString(text);
-
-  return {
-    taskId,
-    taskType,
-    title,
-    description: text.substring(0, 3000),
-    status: "In Progress",
-    assignee: "Unassigned",
-    acceptanceCriteria: extractCriteria(text),
-    context: {
-      files: extractFiles(text),
-      relatedTickets: extractRelatedTickets(text),
-    },
-    metadata: {
-      created: new Date().toISOString(),
-      updated: new Date().toISOString(),
-      loadedFrom: "file",
-      adapter: "file",
-    },
-  };
-}
-
-// ──────────────────────────────────────────────────────────────
-// Credentials loader — global (~/.aiflow/credentials.json) with project fallback
-// ──────────────────────────────────────────────────────────────
-
-async function loadCredentials() {
-  const globalCredsFile = path.join(
-    os.homedir(),
-    ".aiflow",
-    "credentials.json",
-  );
-  if (await fs.pathExists(globalCredsFile)) {
-    const data = await fs.readJson(globalCredsFile).catch(() => ({}));
-    if (data.mcp && Object.keys(data.mcp).length > 0) return data.mcp;
-  }
-  // Fallback: project-level credentials (legacy support)
-  const projectCredsFile = path.join(
-    PROJECT_DIR,
-    ".aiflow",
-    "credentials.json",
-  );
-  if (await fs.pathExists(projectCredsFile)) {
-    return await fs.readJson(projectCredsFile).catch(() => ({}));
-  }
-  return {};
-}
-
-// ──────────────────────────────────────────────────────────────
-// Context persistence
-// ──────────────────────────────────────────────────────────────
-
-async function saveContext(context, saveName) {
-  await fs.ensureDir(CONTEXT_DIR);
-  await fs.ensureDir(path.join(CONTEXT_DIR, "history"));
-
-  // Auto-pause any currently active task that differs from this one
-  const currentFile = path.join(CONTEXT_DIR, "current.json");
-  if (context.taskId && (await fs.pathExists(currentFile))) {
-    const prev = await fs.readJson(currentFile).catch(() => null);
-    if (prev && prev.taskId && prev.taskId !== context.taskId) {
-      try {
-        const { createOrActivateTaskState } = require("./task");
-        // Save previous task state as pending before switching
-        const prevTaskDir = path.join(AIFLOW_DIR, "tasks", prev.taskId);
-        const prevStatePath = path.join(prevTaskDir, "task-state.json");
-        await fs.ensureDir(prevTaskDir);
-        await fs.writeJson(path.join(prevTaskDir, "context.json"), prev, {
-          spaces: 2,
-        });
-        const prevState = (await fs.pathExists(prevStatePath))
-          ? await fs.readJson(prevStatePath).catch(() => ({}))
-          : {};
-        const now = new Date().toISOString();
-        await fs.writeJson(
-          prevStatePath,
-          {
-            ...prevState,
-            taskId: prev.taskId,
-            title: prev.title || "",
-            status: "pending",
-            updatedAt: now,
-            pausedAt: now,
-            currentGate: prevState.currentGate || 1,
-            gateApprovals: prevState.gateApprovals || {},
-            notes: prevState.notes || "",
-            createdAt: prevState.createdAt || now,
-          },
-          { spaces: 2 },
-        );
-        console.log(chalk.gray(`  Auto-paused previous task: ${prev.taskId}`));
-      } catch (_) {
-        /* task module not available */
-      }
-    }
-  }
-
-  // Save as current
-  await fs.writeJson(currentFile, context, { spaces: 2 });
-
-  // Save to history
-  const histFile = path.join(
-    CONTEXT_DIR,
-    "history",
-    `${context.taskId || "manual"}.json`,
-  );
-  await fs.writeJson(histFile, context, { spaces: 2 });
-
-  // Save named snapshot if requested
-  if (saveName) {
-    const namedFile = path.join(CONTEXT_DIR, "history", `${saveName}.json`);
-    await fs.writeJson(namedFile, context, { spaces: 2 });
-    console.log(chalk.gray(`  Context also saved as: ${saveName}`));
-  }
-
-  // Create / activate task-state for the new task
-  if (context.taskId) {
-    try {
-      const { createOrActivateTaskState } = require("./task");
-      await createOrActivateTaskState(context);
-    } catch (_) {
-      /* task module not available */
-    }
-  }
-
-  // Update state
-  if (await fs.pathExists(STATE_FILE)) {
-    const state = await fs.readJson(STATE_FILE);
-    state.current_context = context.taskId;
-    state.current_context_type = context.taskType;
-    await fs.writeJson(STATE_FILE, state);
-  }
-}
-
-// ──────────────────────────────────────────────────────────────
-// Helpers
-// ──────────────────────────────────────────────────────────────
-
-function detectTaskType(issue) {
-  const name = issue.issueType?.name || issue.type?.name || "";
-  const summary = issue.summary || "";
-  return detectTaskTypeFromString(name || summary);
-}
-
-function detectTaskTypeFromString(text) {
-  const lower = text.toLowerCase();
-  if (["bug", "defect", "バグ"].some((k) => lower.includes(k)))
-    return "bug-fix";
-  if (["task", "story", "feature", "タスク"].some((k) => lower.includes(k)))
-    return "feature";
-  if (["research", "investigation", "調査"].some((k) => lower.includes(k)))
-    return "investigation";
-  return "bug-fix"; // default for unknown
-}
-
-function extractCriteria(text) {
-  const lines = text.split("\n");
-  return lines
-    .filter((l) => l.trim().match(/^[-*•]|^\d+\./))
-    .map((l) => l.replace(/^[-*•\d.]+\s*/, "").trim())
-    .filter((l) => l.length > 0)
-    .slice(0, 10);
-}
-
-function extractFiles(text) {
-  const matches = text.match(/[\w/]+\.(php|js|ts|vue|jsx|tsx|css|html)/g) || [];
-  return [...new Set(matches)];
-}
-
-function extractRelatedTickets(text) {
-  const matches = text.match(/[A-Z][A-Z0-9_]+-\d+/g) || [];
-  return [...new Set(matches)];
-}
-
-function printContextSummary(context) {
-  console.log(chalk.green("\n✓ Context loaded\n"));
-  console.log(`  ${chalk.white("Ticket:")}   ${context.taskId}`);
-  console.log(`  ${chalk.white("Type:")}     ${context.taskType}`);
-  console.log(
-    `  ${chalk.white("Title:")}    ${context.title.substring(0, 70)}`,
-  );
-  console.log(`  ${chalk.white("Status:")}   ${context.status}`);
-  console.log(`  ${chalk.white("Assignee:")} ${context.assignee}`);
-  if (context.description) {
-    console.log(
-      `  ${chalk.white("Desc:")}     ${context.description.substring(0, 80)}...`,
-    );
-  }
-  if (context.acceptanceCriteria?.length) {
-    console.log(
-      `  ${chalk.white("Criteria:")} ${context.acceptanceCriteria.length} item(s)`,
-    );
-  }
-  if (context.commentCount > 0) {
-    console.log(
-      `  ${chalk.white("Comments:")} ${context.commentCount} comment(s) loaded`,
-    );
-  }
-  console.log();
-}
-
-// ── GitNexus index status notification ───────────────────────────
-// Called at the top of use() so ALL AI tools (Claude/Gemini/Cursor/Copilot)
-// see the notification when developer runs `aiflow use TICKET`.
-const GITNEXUS_STALE_MS = 3 * 60 * 60 * 1000; // 3 hours — if still "running" after this, process died
-
-async function checkGitNexusIndexStatus() {
-  const statusPath = path.join(AIFLOW_DIR, "gitnexus-status.json");
-  try {
-    if (!(await fs.pathExists(statusPath))) return;
-    const gn = await fs.readJson(statusPath);
-    if (gn.notified) return;
-
-    // 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";
-        gn.notified = false;
-        await fs.writeJson(statusPath, gn, { spaces: 2 });
-      }
-    }
-
-    if (gn.status === "done") {
-      console.log(
-        chalk.green(
-          "✓ GitNexus indexing complete — code intelligence tools are ready.",
-        ),
-      );
-      gn.notified = true;
-      await fs.writeJson(statusPath, gn, { spaces: 2 });
-    } else if (gn.status === "error") {
-      const detail = gn.error
-        ? ` (${gn.error})`
-        : gn.exitCode
-          ? ` (exit ${gn.exitCode})`
-          : "";
-      console.log(chalk.red(`✗ GitNexus indexing failed${detail}.`));
-      // console.log(chalk.gray('  Retry: aiflow init --with-gitnexus'));
-      gn.notified = true;
-      await fs.writeJson(statusPath, gn, { spaces: 2 });
-    }
-    // status === 'running' and not yet stale: still in progress, stay silent
-  } catch (_) {}
-}
-
-async function suggestNextStep() {
-  let aiTools = ["claude"]; // Default
-  try {
-    if (await fs.pathExists(STATE_FILE)) {
-      const state = await fs.readJson(STATE_FILE);
-      if (state.aiTools && state.aiTools.length) {
-        aiTools = state.aiTools;
-      }
-    }
-  } catch (_) {}
-
-  console.log(chalk.cyan("\nNext Steps:"));
-
-  const hasCLI = aiTools.includes("claude") || aiTools.includes("gemini");
-  const hasIDE =
-    aiTools.includes("claude") ||
-    aiTools.includes("cursor") ||
-    aiTools.includes("copilot");
-
-  if (hasCLI) {
-    console.log(chalk.white("\n  CLI:"));
-    let step = 0;
-    if (aiTools.includes("claude")) {
-      console.log(
-        `    ${++step}. ${chalk.white("Claude:")} Run ${chalk.bold.green("claude start")} in terminal. ${chalk.gray("(Quickest way to start)")}`,
-      );
-    }
-    if (aiTools.includes("gemini")) {
-      console.log(
-        `    ${++step}. ${chalk.white("Gemini:")} Run ${chalk.bold.green("gemini")} then type ${chalk.bold.green('"start"')} or ${chalk.bold.green('"Gate 1"')}.`,
-      );
-    }
-  }
-
-  if (hasIDE) {
-    console.log(chalk.white("\n  IDE Extension Chat:"));
-    console.log(
-      `    Run ${chalk.bold.green("aiflow prompt")} → prompt auto-copied to clipboard → paste into your AI extension chat.`,
-    );
-  }
-
-  console.log(
-    `\n  ${chalk.yellow("Note:")} If the AI does not start automatically, type ${chalk.bold.green('"Gate 1"')} or ${chalk.bold.green('"Analyze ticket"')} to begin.`,
-  );
-  console.log();
-}
-
-async function loadTargetAsSupplementaryContext(target, creds, alreadyIds) {
-  if (!target) return null;
-
-  // File path (not a ticket ID, not a backlog URL)
-  if (!isTicketId(target) && !isBacklogUrl(target)) {
-    try {
-      const raw = await fs.readFile(target, 'utf-8');
-      return {
-        sourceType: 'file',
-        sourcePath: target,
-        title: path.basename(target),
-        content: raw.substring(0, 3000),
-      };
-    } catch (err) {
-      console.log(chalk.yellow(`  ⚠ Could not read file: ${target}`));
-      return null;
-    }
-  }
-
-  const issueKey = isBacklogUrl(target) ? extractBacklogId(target) : target;
-  if (!issueKey || alreadyIds.includes(issueKey)) return null;
-
-  const adapter = await resolveTicketAdapter();
-
-  try {
-    if (adapter === 'jira') {
-      const token = creds.JIRA_API_TOKEN;
-      const email = creds.JIRA_EMAIL;
-      const domain = creds.JIRA_DOMAIN;
-      if (!token || !email || !domain) return null;
-      const issue = await fetchJiraIssue(domain, email, token, issueKey);
-      const fields = issue.fields || {};
-      const desc = (fields.description?.content || [])
-        .map(b => (b.content || []).map(c => c.text || '').join('')).join('\n');
-      return {
-        sourceType: 'ticket',
-        sourceUrl: `https://${domain}.atlassian.net/browse/${issueKey}`,
-        ticketId: issueKey,
-        title: fields.summary || '',
-        description: desc.substring(0, 2000),
-      };
-    }
-    const apiKey = creds.BACKLOG_API_KEY;
-    const spaceKey = creds.BACKLOG_SPACE_KEY || creds.BACKLOG_DOMAIN;
-    if (!apiKey || !spaceKey) return null;
-    const domain = spaceKey.includes('.') ? spaceKey : `${spaceKey}.backlog.com`;
-    const issue = await fetchBacklogIssue(domain, apiKey, issueKey);
-    return {
-      sourceType: 'ticket',
-      sourceUrl: `https://${domain}/view/${issueKey}`,
-      ticketId: issueKey,
-      title: issue.summary || '',
-      description: (issue.description || '').substring(0, 2000),
-    };
-  } catch (err) {
-    console.log(chalk.yellow(`  ⚠ Could not load supplementary ${issueKey}: ${err.message}`));
-    return null;
-  }
-}
-
-async function enrichWithSupplementary(supplementaryTargets) {
-  const currentFile = path.join(CONTEXT_DIR, 'current.json');
-  if (!(await fs.pathExists(currentFile))) return;
-
-  const ctx = await fs.readJson(currentFile).catch(() => null);
-  if (!ctx) return;
-
-  const creds = await loadCredentials();
-  const supplementary = [];
-  const alreadyIds = [ctx.taskId].filter(Boolean);
-
-  for (const t of supplementaryTargets) {
-    const sc = await loadTargetAsSupplementaryContext(t, creds, alreadyIds);
-    if (sc) {
-      supplementary.push(sc);
-      if (sc.ticketId) alreadyIds.push(sc.ticketId);
-    }
-  }
-
-  if (ctx.description) {
-    const { resolveLinks } = require('./link-resolver');
-    const linked = await resolveLinks(ctx.description, creds, alreadyIds);
-    supplementary.push(...linked);
-  }
-
-  if (supplementary.length > 0) {
-    ctx.supplementaryContext = supplementary;
-    await fs.writeJson(currentFile, ctx, { spaces: 2 });
-    const histFile = path.join(CONTEXT_DIR, 'history', `${ctx.taskId || 'manual'}.json`);
-    if (await fs.pathExists(path.dirname(histFile))) {
-      await fs.writeJson(histFile, ctx, { spaces: 2 });
-    }
-    console.log(chalk.green(`  ✓ ${supplementary.length} supplementary context(s) linked`));
-  }
-}
-
-module.exports = useCommand;
-module.exports.loadCredentials = loadCredentials;
+const fs = require("fs-extra");
+const path = require("path");
+const os = require("os");
+const chalk = require("chalk");
+const https = require("https");
+const { select, input } = require("@inquirer/prompts");
+
+const PROJECT_DIR = process.cwd();
+const AIFLOW_DIR = path.join(PROJECT_DIR, ".aiflow");
+const STATE_FILE = path.join(AIFLOW_DIR, "state.json");
+const CONTEXT_DIR = path.join(PROJECT_DIR, ".aiflow", "context");
+
+// ──────────────────────────────────────────────────────────────
+// Entry point
+// ──────────────────────────────────────────────────────────────
+
+const useCommand = async function use(targets, options = {}) {
+  // Normalize: accept string (legacy) or array (new multi-target)
+  const targetList = Array.isArray(targets) ? targets.filter(Boolean) : (targets ? [targets] : []);
+  const primaryTarget = targetList[0] || null;
+  const supplementaryTargets = targetList.slice(1);
+
+  if (!(await fs.pathExists(STATE_FILE))) {
+    console.log(
+      chalk.red("Project is not initialized. Run `aiflow init` first."),
+    );
+    return;
+  }
+
+  // ── GitNexus index notification (all AI tools see this) ──────
+  await checkGitNexusIndexStatus();
+
+  // ── Manual entry ──
+  if (options.manual) {
+    return await manualContext();
+  }
+
+  // ── Load from local file ──
+  if (options.file) {
+    return await loadFromFile(options.file, options);
+  }
+
+  // ── No target → version switcher ──
+  if (!primaryTarget) {
+    return await switchVersion();
+  }
+
+  // ── Detect target type and dispatch ──
+  if (isVersion(primaryTarget)) {
+    return await switchVersion(primaryTarget);
+  }
+
+  if (isTicketId(primaryTarget)) {
+    const adapter = await resolveTicketAdapter();
+    if (adapter === "jira") await loadFromJira(primaryTarget, options);
+    else await loadFromBacklog(primaryTarget, options);
+    return await enrichWithSupplementary(supplementaryTargets);
+  }
+
+  if (isBacklogUrl(primaryTarget)) {
+    const id = extractBacklogId(primaryTarget);
+    await loadFromBacklog(id, options);
+    return await enrichWithSupplementary(supplementaryTargets);
+  }
+
+  // ── Fallback: try Backlog then manual ──
+  console.log(chalk.yellow(`Cannot detect format for: ${primaryTarget}`));
+  console.log(
+    chalk.gray("Supported: PROJ-33, APP-123, version number, --manual"),
+  );
+  return await manualContext();
+};
+
+// ──────────────────────────────────────────────────────────────
+// Detectors
+// ──────────────────────────────────────────────────────────────
+
+function isVersion(s) {
+  return /^\d+\.\d+\.\d+$/.test(s);
+}
+
+/** Both Backlog and Jira use the same PROJECT-NUMBER format. */
+function isTicketId(s) {
+  return /^[A-Z][A-Z0-9_]+-\d+$/.test(s);
+}
+
+/**
+ * Determine which adapter to use for a ticket ID based on configured adapters
+ * in state.json. Falls back to backlog if both or neither are configured.
+ */
+async function resolveTicketAdapter() {
+  try {
+    if (await fs.pathExists(STATE_FILE)) {
+      const state = await fs.readJson(STATE_FILE);
+      const adapters = state.adapters || [];
+      if (adapters.includes("jira") && !adapters.includes("backlog")) {
+        return "jira";
+      }
+    }
+  } catch (_) {
+    /* ignore */
+  }
+  return "backlog";
+}
+
+function isBacklogUrl(s) {
+  return s.includes("backlog.com/view/") || s.includes("backlogtool.com/view/");
+}
+
+function extractBacklogId(url) {
+  const match = url.match(/\/view\/([A-Z][A-Z0-9_]+-\d+)/);
+  return match ? match[1] : null;
+}
+
+// ──────────────────────────────────────────────────────────────
+// Version switcher (original behavior)
+// ──────────────────────────────────────────────────────────────
+
+async function switchVersion(versionReq) {
+  const versionsDir = path.join(AIFLOW_DIR, "versions");
+  if (!(await fs.pathExists(versionsDir))) {
+    console.log(chalk.red("No versions directory found."));
+    return;
+  }
+
+  const available = await fs.readdir(versionsDir);
+  if (!available.length) {
+    console.log(chalk.red("No installed versions found."));
+    return;
+  }
+
+  let targetVersion = versionReq;
+  if (!targetVersion) {
+    targetVersion = await select({
+      message: "Select version to use:",
+      choices: available.map((v) => ({ name: `v${v}`, value: v })),
+    });
+  }
+
+  if (!available.includes(targetVersion)) {
+    console.log(chalk.red(`Version v${targetVersion} is not installed.`));
+    return;
+  }
+
+  console.log(chalk.blue(`Switching to v${targetVersion}...`));
+  const versionDir = path.join(versionsDir, targetVersion);
+
+  const claudeDir = path.join(PROJECT_DIR, ".claude");
+  await fs.emptyDir(claudeDir);
+  await fs.copy(
+    path.join(versionDir, "skills"),
+    path.join(claudeDir, "skills"),
+    { overwrite: true },
+  );
+
+  const rulesDir = path.join(PROJECT_DIR, ".rules");
+  await fs.emptyDir(rulesDir);
+  await fs.copy(path.join(versionDir, "rules"), rulesDir, { overwrite: true });
+
+  const state = await fs.readJson(STATE_FILE);
+  state.current_version = targetVersion;
+  await fs.writeJson(STATE_FILE, state);
+
+  console.log(chalk.green(`✓ Switched to v${targetVersion}.`));
+}
+
+// ──────────────────────────────────────────────────────────────
+// Backlog context loader
+// ──────────────────────────────────────────────────────────────
+
+async function loadFromBacklog(issueKey, options = {}) {
+  const creds = await loadCredentials();
+  const apiKey = process.env.BACKLOG_API_KEY || creds.BACKLOG_API_KEY;
+  const spaceKey =
+    process.env.BACKLOG_SPACE_KEY ||
+    creds.BACKLOG_SPACE_KEY ||
+    process.env.BACKLOG_DOMAIN ||
+    creds.BACKLOG_DOMAIN;
+
+  if (!apiKey || !spaceKey) {
+    console.log(chalk.yellow("⚠ Backlog credentials not set."));
+    console.log(chalk.gray("Run: aiflow init --adapter backlog"));
+    console.log(chalk.gray("Or set environment variables:"));
+    console.log(chalk.gray("  BACKLOG_API_KEY=your-api-key"));
+    console.log(chalk.gray("  BACKLOG_SPACE_KEY=your-space (e.g. mycompany)"));
+    console.log(chalk.gray("\nFalling back to manual entry...\n"));
+    return await manualContext(issueKey);
+  }
+
+  // spaceKey can be full domain (mycompany.backlog.com) or just the space (mycompany)
+  const domain = spaceKey.includes(".") ? spaceKey : `${spaceKey}.backlog.com`;
+
+  console.log(chalk.blue(`Fetching context from Backlog: ${issueKey}...`));
+
+  try {
+    // Default: description only. Comments loaded only when explicitly requested.
+    const loadComments =
+      options.coms ||
+      options.withComs ||
+      options.withComments ||
+      options["with-comments"] ||
+      options.with_comments ||
+      options.cid != null ||
+      options.commentId != null ||
+      options["comment-id"] != null ||
+      options.clast != null ||
+      options.commentsLast != null ||
+      options.cfrom != null ||
+      options.commentsFrom != null ||
+      options.cto != null ||
+      options.commentsTo != null ||
+      options["comments-to"] != null;
+    
+    if (loadComments) {
+      console.log(chalk.gray("  ℹ Comments requested..."));
+    }
+    const [issue, rawComments] = await Promise.all([
+      fetchBacklogIssue(domain, apiKey, issueKey),
+      loadComments
+        ? fetchBacklogComments(domain, apiKey, issueKey)
+        : Promise.resolve([]),
+    ]);
+
+    const comments = filterComments(rawComments, options);
+    if (loadComments) {
+      console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
+    }
+    const context = buildContextFromBacklog(issue, comments, issueKey, domain);
+    context.mode = options.full ? "full" : "fast";
+    await saveContext(context, options.save);
+    printContextSummary(context);
+    await suggestNextStep();
+  } catch (err) {
+    console.log(chalk.yellow(`⚠ Could not fetch from Backlog: ${err.message}`));
+    console.log(chalk.gray("Falling back to manual entry...\n"));
+    await manualContext(issueKey);
+  }
+}
+
+/**
+ * Filter comments array based on CLI options:
+ *   --no-comments      → empty array (already handled upstream, but safe here too)
+ *   --comments-last N  → last N comments
+ *   --comments-from N  → comments starting at index N (0-based)
+ *   (default)          → all comments
+ */
+function filterComments(comments, options = {}) {
+  if (!comments || !comments.length) return [];
+
+  let result = [...comments];
+
+  // 1. Filter by specific ID if provided
+  const targetId = options.cid || options.commentId || options["comment-id"];
+  if (targetId) {
+    result = result.filter((c) => String(c.id) === String(targetId));
+  }
+
+  // 2. Filter by starting ID (from)
+  const fromId = options.cfrom || options.commentsFrom || options["comments-from"];
+  if (fromId) {
+    result = result.filter((c) => Number(c.id) >= Number(fromId));
+  }
+
+  // 3. Filter by ending ID (to)
+  const toId = options.cto || options.commentsTo || options["comments-to"];
+  if (toId) {
+    result = result.filter((c) => Number(c.id) <= Number(toId));
+  }
+
+  // 4. Filter by last N comments (if not using specific ID/range filters)
+  const lastN = options.clast || options.commentsLast;
+  if (lastN != null && !targetId && !fromId && !toId) {
+    const n = Math.max(1, lastN);
+    return result.slice(-n);
+  }
+
+  return result;
+}
+
+/**
+ * Generic Backlog GET helper
+ */
+function backlogGet(url) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(data));
+          } catch (e) {
+            reject(new Error("Invalid JSON response from Backlog"));
+          }
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+/**
+ * Fetch issue detail from Backlog REST API
+ */
+function fetchBacklogIssue(domain, apiKey, issueKey) {
+  return backlogGet(
+    `https://${domain}/api/v2/issues/${issueKey}?apiKey=${apiKey}`,
+  );
+}
+
+/**
+ * Fetch ALL comments of an issue from Backlog REST API.
+ * Uses minId for pagination because 'offset' is not supported for comments.
+ */
+async function fetchBacklogComments(domain, apiKey, issueKey) {
+  const all = [];
+  let minId = null;
+  try {
+    while (true) {
+      let url = `https://${domain}/api/v2/issues/${issueKey}/comments?apiKey=${apiKey}&count=100&order=asc`;
+      if (minId) {
+        url += `&minId=${minId}`;
+      }
+      
+      const batch = await backlogGet(url);
+      if (!batch || batch.length === 0) break;
+      
+      all.push(...batch);
+      if (batch.length < 100) break;
+      
+      // Use the last ID as minId for the next batch
+      minId = batch[batch.length - 1].id;
+    }
+  } catch (err) {
+    console.log(
+      chalk.yellow(`  ⚠ Warning: Could not fetch comments: ${err.message}`),
+    );
+  }
+  return all;
+}
+
+/**
+ * Transform Backlog API response + comments to internal context format
+ */
+function buildContextFromBacklog(issue, comments, issueKey, domain) {
+  const type = detectTaskType(issue);
+
+  // Format comments into readable text for AI context
+  const formattedComments = (comments || [])
+    .map((c) => {
+      // Backlog comments can have text in 'content' or be just changelogs
+      const text = c.content || "";
+      if (!text.trim()) return null;
+
+      const author = c.createdUser?.name || "Unknown";
+      const date = c.created
+        ? new Date(c.created).toLocaleDateString("vi-VN")
+        : "";
+      return `[${author} - ${date}]\n${text.trim()}`;
+    })
+    .filter(Boolean);
+
+  const allText = [
+    issue.description || "",
+    ...formattedComments.map((c) => c),
+  ].join("\n");
+
+  return {
+    taskId: issueKey,
+    taskType: type,
+    title: issue.summary || "",
+    description: issue.description || "",
+    status: issue.status?.name || "Unknown",
+    priority: issue.priority?.name || "Unknown",
+    assignee: issue.assignee?.name || "Unassigned",
+
+    // Comments from all participants
+    comments: formattedComments,
+    commentCount: formattedComments.length,
+
+    // Parse checklist-style acceptance criteria from description
+    acceptanceCriteria: extractCriteria(issue.description || ""),
+
+    // Related files mentioned anywhere in ticket
+    context: {
+      files: extractFiles(allText),
+      mentionedServices: [],
+      relatedTickets: extractRelatedTickets(allText),
+    },
+
+    metadata: {
+      created: issue.created,
+      updated: issue.updated,
+      loadedFrom: "backlog",
+      adapter: "backlog",
+      sourceUrl: `https://${domain}/view/${issueKey}`,
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────
+// Jira context loader
+// ──────────────────────────────────────────────────────────────
+
+async function loadFromJira(issueKey, options = {}) {
+  const creds = await loadCredentials();
+  const apiToken = process.env.JIRA_API_TOKEN || creds.JIRA_API_TOKEN;
+  const email = process.env.JIRA_EMAIL || creds.JIRA_EMAIL;
+  const domain = process.env.JIRA_DOMAIN || creds.JIRA_DOMAIN;
+
+  if (!apiToken || !email || !domain) {
+    console.log(chalk.yellow("⚠ Jira credentials not set."));
+    console.log(chalk.gray("Run: aiflow init --adapter jira"));
+    console.log(
+      chalk.gray(
+        "Or set environment variables: JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN",
+      ),
+    );
+    console.log(chalk.gray("\nFalling back to manual entry...\n"));
+    return await manualContext(issueKey);
+  }
+
+  console.log(chalk.blue(`Fetching context from Jira: ${issueKey}...`));
+
+  try {
+    const loadComments =
+      options.coms ||
+      options.withComs ||
+      options.withComments ||
+      options["with-comments"] ||
+      options.with_comments ||
+      options.cid != null ||
+      options.commentId != null ||
+      options["comment-id"] != null ||
+      options.clast != null ||
+      options.commentsLast != null ||
+      options.cfrom != null ||
+      options.commentsFrom != null ||
+      options.cto != null ||
+      options.commentsTo != null ||
+      options["comments-to"] != null;
+    
+    if (loadComments) {
+      console.log(chalk.gray("  ℹ Comments requested..."));
+    }
+    const [issue, rawComments] = await Promise.all([
+      fetchJiraIssue(domain, email, apiToken, issueKey),
+      loadComments
+        ? fetchJiraComments(domain, email, apiToken, issueKey)
+        : Promise.resolve([]),
+    ]);
+
+    const comments = filterComments(rawComments, options);
+    if (loadComments) {
+      console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
+    }
+    const context = buildContextFromJira(issue, comments, issueKey, domain);
+    context.mode = options.full ? "full" : "fast";
+    await saveContext(context, options.save);
+    printContextSummary(context);
+    await suggestNextStep();
+  } catch (err) {
+    console.log(chalk.yellow(`⚠ Could not fetch from Jira: ${err.message}`));
+    console.log(chalk.gray("Falling back to manual entry...\n"));
+    await manualContext(issueKey);
+  }
+}
+
+function fetchJiraIssue(domain, email, apiToken, issueKey) {
+  return new Promise((resolve, reject) => {
+    const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
+    const url = `https://${domain}.atlassian.net/rest/api/3/issue/${issueKey}`;
+    const options = {
+      headers: {
+        Authorization: `Basic ${auth}`,
+        Accept: "application/json",
+      },
+    };
+
+    https
+      .get(url, options, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(data));
+          } catch (e) {
+            reject(new Error("Invalid JSON response from Jira"));
+          }
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+/**
+ * Fetch ALL comments of an issue from Jira REST API.
+ */
+async function fetchJiraComments(domain, email, apiToken, issueKey) {
+  return new Promise((resolve, reject) => {
+    const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
+    const url = `https://${domain}.atlassian.net/rest/api/3/issue/${issueKey}/comment`;
+    const options = {
+      headers: {
+        Authorization: `Basic ${auth}`,
+        Accept: "application/json",
+      },
+    };
+
+    https
+      .get(url, options, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            // Comments are optional, but log if we failed
+            console.log(
+              chalk.yellow(
+                `  ⚠ Warning: Jira comments API returned ${res.statusCode}`,
+              ),
+            );
+            resolve([]);
+            return;
+          }
+          try {
+            const json = JSON.parse(data);
+            resolve(json.comments || []);
+          } catch (e) {
+            resolve([]);
+          }
+        });
+      })
+      .on("error", () => resolve([]));
+  });
+}
+
+function buildContextFromJira(issue, comments, issueKey, domain) {
+  const fields = issue.fields || {};
+  const type = detectTaskTypeFromString(fields.issuetype?.name || "");
+
+  // Format comments for Jira (v3 uses ADF format for body)
+  const formattedComments = (comments || [])
+    .map((c) => {
+      const author = c.author?.displayName || "Unknown";
+      const date = c.created
+        ? new Date(c.created).toLocaleDateString("vi-VN")
+        : "";
+      const body =
+        c.body?.content
+          ?.map(
+            (block) => block.content?.map((inner) => inner.text).join("") || "",
+          )
+          .join("\n") || "";
+      return body.trim() ? `[${author} - ${date}]\n${body.trim()}` : null;
+    })
+    .filter(Boolean);
+
+  return {
+    taskId: issueKey,
+    taskType: type,
+    title: fields.summary || "",
+    description:
+      fields.description?.content
+        ?.map((block) => block.content?.map((c) => c.text).join("") || "")
+        .join("\n") || "",
+    status: fields.status?.name || "Unknown",
+    priority: fields.priority?.name || "Unknown",
+    assignee: fields.assignee?.displayName || "Unassigned",
+
+    // Comments
+    comments: formattedComments,
+    commentCount: formattedComments.length,
+
+    acceptanceCriteria: extractCriteria(fields.description?.toString() || ""),
+    context: {
+      files: [],
+      relatedTickets: [],
+    },
+    metadata: {
+      created: fields.created,
+      updated: fields.updated,
+      loadedFrom: "jira",
+      adapter: "jira",
+      sourceUrl: `https://${domain}.atlassian.net/browse/${issueKey}`,
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────
+// Manual context entry
+// ──────────────────────────────────────────────────────────────
+
+async function manualContext(prefillId = "") {
+  // Load existing context for pre-fill (Edit mode)
+  let existing = {};
+  const currentPath = path.join(CONTEXT_DIR, "current.json");
+  if (await fs.pathExists(currentPath)) {
+    existing = await fs.readJson(currentPath).catch(() => ({}));
+  }
+
+  const isEdit = !!existing.taskId;
+  if (isEdit) {
+    console.log(chalk.cyan("\nEdit Context\n"));
+    console.log(
+      chalk.gray("Press Enter to keep existing value shown in [brackets]\n"),
+    );
+  } else {
+    console.log(chalk.cyan("\nManual Context Entry\n"));
+  }
+
+  // Ticket ID
+  const defaultId = prefillId || existing.taskId || "";
+  const idHint = defaultId ? chalk.gray(` [${defaultId}]`) : "";
+  const idInput = await input({
+    message: `Ticket ID (e.g. PROJ-33)${idHint}:`,
+    default: "",
+  });
+  const taskId = idInput.trim() || defaultId;
+
+  // Title
+  const defaultTitle = existing.title || "";
+  const titlePreview =
+    defaultTitle.length > 50
+      ? defaultTitle.substring(0, 50) + "…"
+      : defaultTitle;
+  const titleHint = defaultTitle ? chalk.gray(` [${titlePreview}]`) : "";
+  const titleInput = await input({
+    message: `Title${titleHint}:`,
+    default: "",
+  });
+  const title = titleInput.trim() || defaultTitle;
+
+  // Description
+  const defaultDesc = existing.description || "";
+  const descPreview =
+    defaultDesc.length > 60 ? defaultDesc.substring(0, 60) + "…" : defaultDesc;
+  const descHint = defaultDesc ? chalk.gray(` [${descPreview}]`) : "";
+  const descInput = await input({
+    message: `Description (brief)${descHint}:`,
+    default: "",
+  });
+  const description = descInput.trim() || defaultDesc;
+
+  // Task type — pre-select existing value if available
+  const taskType = await select({
+    message: "Task type:",
+    choices: [
+      { name: "🐛 Bug Fix", value: "bug-fix" },
+      { name: "✨ Feature", value: "feature" },
+      { name: "🔍 Investigation", value: "investigation" },
+      { name: "♻️  Refactor", value: "refactor" },
+      { name: "📊 Impact Analysis", value: "impact-analysis" },
+      { name: "📖 Documentation", value: "documentation" },
+    ],
+    default: existing.taskType || undefined,
+  });
+
+  const context = {
+    taskId,
+    taskType,
+    title,
+    description,
+    status: existing.status || "In Progress",
+    mode: existing.mode || "auto",
+    acceptanceCriteria: existing.acceptanceCriteria || [],
+    context: existing.context || { files: [], relatedTickets: [] },
+    metadata: {
+      created: existing.metadata?.created || new Date().toISOString(),
+      updated: new Date().toISOString(),
+      loadedFrom: "manual",
+      adapter: "manual",
+    },
+  };
+
+  await saveContext(context);
+  printContextSummary(context);
+  await suggestNextStep();
+}
+
+// ──────────────────────────────────────────────────────────────
+// Load from JSON file
+// ──────────────────────────────────────────────────────────────
+
+async function loadFromFile(filePath, options = {}) {
+  if (!(await fs.pathExists(filePath))) {
+    console.log(chalk.red(`File not found: ${filePath}`));
+    return;
+  }
+
+  const raw = await fs.readFile(filePath, "utf-8");
+  let context;
+
+  // Try JSON first; fall back to plain-text auto-detection
+  try {
+    context = JSON.parse(raw);
+  } catch (_) {
+    console.log(
+      chalk.gray(
+        "  File is not JSON — auto-detecting task info from content...",
+      ),
+    );
+    context = buildContextFromPlainText(raw, filePath);
+  }
+
+  context.mode = options.full ? "full" : "fast";
+
+  // Prompt for task type
+  context.taskType = await select({
+    message: "Task type:",
+    choices: [
+      { name: "🐛 Bug Fix", value: "bug-fix" },
+      { name: "✨ Feature", value: "feature" },
+      { name: "🔍 Investigation", value: "investigation" },
+      { name: "♻️  Refactor", value: "refactor" },
+      { name: "📊 Impact Analysis", value: "impact-analysis" },
+      { name: "📖 Documentation", value: "documentation" },
+    ],
+    default: context.taskType || "feature",
+  });
+
+  await saveContext(context, options.save);
+  printContextSummary(context);
+  await suggestNextStep();
+}
+
+/**
+ * Build a minimal context object from arbitrary plain-text file content.
+ * Tries to detect ticket ID (e.g. PROJ-33, APP-123) and a title from the first non-blank line.
+ */
+function buildContextFromPlainText(text, filePath = "") {
+  // Detect ticket ID: first PROJ-123 style token anywhere in the text
+  const idMatch = text.match(/\b([A-Z][A-Z0-9_]+-\d+)\b/);
+
+  let taskId;
+  if (idMatch) {
+    taskId = idMatch[1];
+  } else {
+    const fileNameOnly = filePath
+      ? path.basename(filePath, path.extname(filePath))
+      : "";
+    const cleanWords = fileNameOnly
+      .replace(/[^a-zA-Z0-9]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean)
+      .slice(0, 5)
+      .join("-")
+      .toUpperCase();
+    const prefix = cleanWords ? `TASK-${cleanWords}-` : "TASK-";
+    taskId = `${prefix}${Date.now()}`;
+  }
+
+  // Title: use full filename if available, otherwise first non-blank line
+  const fullFileName = filePath ? path.basename(filePath) : "";
+  const lines = text
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const titleLine = fullFileName || lines.find((l) => l.length > 3) || taskId;
+  const title = titleLine.substring(0, 120);
+
+  // Task type detection from text
+  const taskType = detectTaskTypeFromString(text);
+
+  return {
+    taskId,
+    taskType,
+    title,
+    description: text.substring(0, 3000),
+    status: "In Progress",
+    assignee: "Unassigned",
+    acceptanceCriteria: extractCriteria(text),
+    context: {
+      files: extractFiles(text),
+      relatedTickets: extractRelatedTickets(text),
+    },
+    metadata: {
+      created: new Date().toISOString(),
+      updated: new Date().toISOString(),
+      loadedFrom: "file",
+      adapter: "file",
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────
+// Credentials loader — global (~/.aiflow/credentials.json) with project fallback
+// ──────────────────────────────────────────────────────────────
+
+async function loadCredentials() {
+  const globalCredsFile = path.join(
+    os.homedir(),
+    ".aiflow",
+    "credentials.json",
+  );
+  if (await fs.pathExists(globalCredsFile)) {
+    const data = await fs.readJson(globalCredsFile).catch(() => ({}));
+    if (data.mcp && Object.keys(data.mcp).length > 0) return data.mcp;
+  }
+  // Fallback: project-level credentials (legacy support)
+  const projectCredsFile = path.join(
+    PROJECT_DIR,
+    ".aiflow",
+    "credentials.json",
+  );
+  if (await fs.pathExists(projectCredsFile)) {
+    return await fs.readJson(projectCredsFile).catch(() => ({}));
+  }
+  return {};
+}
+
+// ──────────────────────────────────────────────────────────────
+// Context persistence
+// ──────────────────────────────────────────────────────────────
+
+async function saveContext(context, saveName) {
+  await fs.ensureDir(CONTEXT_DIR);
+  await fs.ensureDir(path.join(CONTEXT_DIR, "history"));
+
+  // Auto-pause any currently active task that differs from this one
+  const currentFile = path.join(CONTEXT_DIR, "current.json");
+  if (context.taskId && (await fs.pathExists(currentFile))) {
+    const prev = await fs.readJson(currentFile).catch(() => null);
+    if (prev && prev.taskId && prev.taskId !== context.taskId) {
+      try {
+        const { createOrActivateTaskState } = require("./task");
+        // Save previous task state as pending before switching
+        const prevTaskDir = path.join(AIFLOW_DIR, "tasks", prev.taskId);
+        const prevStatePath = path.join(prevTaskDir, "task-state.json");
+        await fs.ensureDir(prevTaskDir);
+        await fs.writeJson(path.join(prevTaskDir, "context.json"), prev, {
+          spaces: 2,
+        });
+        const prevState = (await fs.pathExists(prevStatePath))
+          ? await fs.readJson(prevStatePath).catch(() => ({}))
+          : {};
+        const now = new Date().toISOString();
+        await fs.writeJson(
+          prevStatePath,
+          {
+            ...prevState,
+            taskId: prev.taskId,
+            title: prev.title || "",
+            status: "pending",
+            updatedAt: now,
+            pausedAt: now,
+            currentGate: prevState.currentGate || 1,
+            gateApprovals: prevState.gateApprovals || {},
+            notes: prevState.notes || "",
+            createdAt: prevState.createdAt || now,
+          },
+          { spaces: 2 },
+        );
+        console.log(chalk.gray(`  Auto-paused previous task: ${prev.taskId}`));
+      } catch (_) {
+        /* task module not available */
+      }
+    }
+  }
+
+  // Save as current
+  await fs.writeJson(currentFile, context, { spaces: 2 });
+
+  // Save to history
+  const histFile = path.join(
+    CONTEXT_DIR,
+    "history",
+    `${context.taskId || "manual"}.json`,
+  );
+  await fs.writeJson(histFile, context, { spaces: 2 });
+
+  // Save named snapshot if requested
+  if (saveName) {
+    const namedFile = path.join(CONTEXT_DIR, "history", `${saveName}.json`);
+    await fs.writeJson(namedFile, context, { spaces: 2 });
+    console.log(chalk.gray(`  Context also saved as: ${saveName}`));
+  }
+
+  // Create / activate task-state for the new task
+  if (context.taskId) {
+    try {
+      const { createOrActivateTaskState } = require("./task");
+      await createOrActivateTaskState(context);
+    } catch (_) {
+      /* task module not available */
+    }
+  }
+
+  // Update state
+  if (await fs.pathExists(STATE_FILE)) {
+    const state = await fs.readJson(STATE_FILE);
+    state.current_context = context.taskId;
+    state.current_context_type = context.taskType;
+    await fs.writeJson(STATE_FILE, state);
+  }
+}
+
+// ──────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────
+
+function detectTaskType(issue) {
+  const name = issue.issueType?.name || issue.type?.name || "";
+  const summary = issue.summary || "";
+  return detectTaskTypeFromString(name || summary);
+}
+
+function detectTaskTypeFromString(text) {
+  const lower = text.toLowerCase();
+  if (["bug", "defect", "バグ"].some((k) => lower.includes(k)))
+    return "bug-fix";
+  if (["task", "story", "feature", "タスク"].some((k) => lower.includes(k)))
+    return "feature";
+  if (["research", "investigation", "調査"].some((k) => lower.includes(k)))
+    return "investigation";
+  return "bug-fix"; // default for unknown
+}
+
+function extractCriteria(text) {
+  const lines = text.split("\n");
+  return lines
+    .filter((l) => l.trim().match(/^[-*•]|^\d+\./))
+    .map((l) => l.replace(/^[-*•\d.]+\s*/, "").trim())
+    .filter((l) => l.length > 0)
+    .slice(0, 10);
+}
+
+function extractFiles(text) {
+  const matches = text.match(/[\w/]+\.(php|js|ts|vue|jsx|tsx|css|html)/g) || [];
+  return [...new Set(matches)];
+}
+
+function extractRelatedTickets(text) {
+  const matches = text.match(/[A-Z][A-Z0-9_]+-\d+/g) || [];
+  return [...new Set(matches)];
+}
+
+function printContextSummary(context) {
+  console.log(chalk.green("\n✓ Context loaded\n"));
+  console.log(`  ${chalk.white("Ticket:")}   ${context.taskId}`);
+  console.log(`  ${chalk.white("Type:")}     ${context.taskType}`);
+  console.log(
+    `  ${chalk.white("Title:")}    ${context.title.substring(0, 70)}`,
+  );
+  console.log(`  ${chalk.white("Status:")}   ${context.status}`);
+  console.log(`  ${chalk.white("Assignee:")} ${context.assignee}`);
+  if (context.description) {
+    console.log(
+      `  ${chalk.white("Desc:")}     ${context.description.substring(0, 80)}...`,
+    );
+  }
+  if (context.acceptanceCriteria?.length) {
+    console.log(
+      `  ${chalk.white("Criteria:")} ${context.acceptanceCriteria.length} item(s)`,
+    );
+  }
+  if (context.commentCount > 0) {
+    console.log(
+      `  ${chalk.white("Comments:")} ${context.commentCount} comment(s) loaded`,
+    );
+  }
+  console.log();
+}
+
+// ── GitNexus index status notification ───────────────────────────
+// Called at the top of use() so ALL AI tools (Claude/Gemini/Cursor/Copilot)
+// see the notification when developer runs `aiflow use TICKET`.
+const GITNEXUS_STALE_MS = 3 * 60 * 60 * 1000; // 3 hours — if still "running" after this, process died
+
+async function checkGitNexusIndexStatus() {
+  const statusPath = path.join(AIFLOW_DIR, "gitnexus-status.json");
+  try {
+    if (!(await fs.pathExists(statusPath))) return;
+    const gn = await fs.readJson(statusPath);
+    if (gn.notified) return;
+
+    // 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";
+        gn.notified = false;
+        await fs.writeJson(statusPath, gn, { spaces: 2 });
+      }
+    }
+
+    if (gn.status === "done") {
+      console.log(
+        chalk.green(
+          "✓ GitNexus indexing complete — code intelligence tools are ready.",
+        ),
+      );
+      gn.notified = true;
+      await fs.writeJson(statusPath, gn, { spaces: 2 });
+    } else if (gn.status === "error") {
+      const detail = gn.error
+        ? ` (${gn.error})`
+        : gn.exitCode
+          ? ` (exit ${gn.exitCode})`
+          : "";
+      console.log(chalk.red(`✗ GitNexus indexing failed${detail}.`));
+      // console.log(chalk.gray('  Retry: aiflow init --with-gitnexus'));
+      gn.notified = true;
+      await fs.writeJson(statusPath, gn, { spaces: 2 });
+    }
+    // status === 'running' and not yet stale: still in progress, stay silent
+  } catch (_) {}
+}
+
+async function suggestNextStep() {
+  let aiTools = ["claude"]; // Default
+  try {
+    if (await fs.pathExists(STATE_FILE)) {
+      const state = await fs.readJson(STATE_FILE);
+      if (state.aiTools && state.aiTools.length) {
+        aiTools = state.aiTools;
+      }
+    }
+  } catch (_) {}
+
+  console.log(chalk.cyan("\nNext Steps:"));
+
+  const hasCLI = aiTools.includes("claude") || aiTools.includes("gemini");
+  const hasIDE =
+    aiTools.includes("claude") ||
+    aiTools.includes("cursor") ||
+    aiTools.includes("copilot");
+
+  if (hasCLI) {
+    console.log(chalk.white("\n  CLI:"));
+    let step = 0;
+    if (aiTools.includes("claude")) {
+      console.log(
+        `    ${++step}. ${chalk.white("Claude:")} Run ${chalk.bold.green("claude start")} in terminal. ${chalk.gray("(Quickest way to start)")}`,
+      );
+    }
+    if (aiTools.includes("gemini")) {
+      console.log(
+        `    ${++step}. ${chalk.white("Gemini:")} Run ${chalk.bold.green("gemini")} then type ${chalk.bold.green('"start"')} or ${chalk.bold.green('"Gate 1"')}.`,
+      );
+    }
+  }
+
+  if (hasIDE) {
+    console.log(chalk.white("\n  IDE Extension Chat:"));
+    console.log(
+      `    Run ${chalk.bold.green("aiflow prompt")} → prompt auto-copied to clipboard → paste into your AI extension chat.`,
+    );
+  }
+
+  console.log(
+    `\n  ${chalk.yellow("Note:")} If the AI does not start automatically, type ${chalk.bold.green('"Gate 1"')} or ${chalk.bold.green('"Analyze ticket"')} to begin.`,
+  );
+  console.log();
+}
+
+async function loadTargetAsSupplementaryContext(target, creds, alreadyIds) {
+  if (!target) return null;
+
+  // File path (not a ticket ID, not a backlog URL)
+  if (!isTicketId(target) && !isBacklogUrl(target)) {
+    try {
+      const raw = await fs.readFile(target, 'utf-8');
+      return {
+        sourceType: 'file',
+        sourcePath: target,
+        title: path.basename(target),
+        content: raw.substring(0, 3000),
+      };
+    } catch (err) {
+      console.log(chalk.yellow(`  ⚠ Could not read file: ${target}`));
+      return null;
+    }
+  }
+
+  const issueKey = isBacklogUrl(target) ? extractBacklogId(target) : target;
+  if (!issueKey || alreadyIds.includes(issueKey)) return null;
+
+  const adapter = await resolveTicketAdapter();
+
+  try {
+    if (adapter === 'jira') {
+      const token = creds.JIRA_API_TOKEN;
+      const email = creds.JIRA_EMAIL;
+      const domain = creds.JIRA_DOMAIN;
+      if (!token || !email || !domain) return null;
+      const issue = await fetchJiraIssue(domain, email, token, issueKey);
+      const fields = issue.fields || {};
+      const desc = (fields.description?.content || [])
+        .map(b => (b.content || []).map(c => c.text || '').join('')).join('\n');
+      return {
+        sourceType: 'ticket',
+        sourceUrl: `https://${domain}.atlassian.net/browse/${issueKey}`,
+        ticketId: issueKey,
+        title: fields.summary || '',
+        description: desc.substring(0, 2000),
+      };
+    }
+    const apiKey = creds.BACKLOG_API_KEY;
+    const spaceKey = creds.BACKLOG_SPACE_KEY || creds.BACKLOG_DOMAIN;
+    if (!apiKey || !spaceKey) return null;
+    const domain = spaceKey.includes('.') ? spaceKey : `${spaceKey}.backlog.com`;
+    const issue = await fetchBacklogIssue(domain, apiKey, issueKey);
+    return {
+      sourceType: 'ticket',
+      sourceUrl: `https://${domain}/view/${issueKey}`,
+      ticketId: issueKey,
+      title: issue.summary || '',
+      description: (issue.description || '').substring(0, 2000),
+    };
+  } catch (err) {
+    console.log(chalk.yellow(`  ⚠ Could not load supplementary ${issueKey}: ${err.message}`));
+    return null;
+  }
+}
+
+async function enrichWithSupplementary(supplementaryTargets) {
+  const currentFile = path.join(CONTEXT_DIR, 'current.json');
+  if (!(await fs.pathExists(currentFile))) return;
+
+  const ctx = await fs.readJson(currentFile).catch(() => null);
+  if (!ctx) return;
+
+  const creds = await loadCredentials();
+  const supplementary = [];
+  const alreadyIds = [ctx.taskId].filter(Boolean);
+
+  for (const t of supplementaryTargets) {
+    const sc = await loadTargetAsSupplementaryContext(t, creds, alreadyIds);
+    if (sc) {
+      supplementary.push(sc);
+      if (sc.ticketId) alreadyIds.push(sc.ticketId);
+    }
+  }
+
+  if (ctx.description) {
+    const { resolveLinks } = require('./link-resolver');
+    const linked = await resolveLinks(ctx.description, creds, alreadyIds);
+    supplementary.push(...linked);
+  }
+
+  if (supplementary.length > 0) {
+    ctx.supplementaryContext = supplementary;
+    await fs.writeJson(currentFile, ctx, { spaces: 2 });
+    const histFile = path.join(CONTEXT_DIR, 'history', `${ctx.taskId || 'manual'}.json`);
+    if (await fs.pathExists(path.dirname(histFile))) {
+      await fs.writeJson(histFile, ctx, { spaces: 2 });
+    }
+    console.log(chalk.green(`  ✓ ${supplementary.length} supplementary context(s) linked`));
+  }
+}
+
+module.exports = useCommand;
+module.exports.loadCredentials = loadCredentials;