@entelligentsia/forgecli 0.7.9 → 0.8.4

package/dist/forge-payload/.tools/lib/store-facade.cjs

@@ -0,0 +1,162 @@
+'use strict';
+// store-facade.cjs — StoreFacade, extractExcerpt, loadForgeConfig
+// Used by store-query.cjs. No dependency on store.cjs or schemas.
+
+const fs = require('fs');
+const path = require('path');
+
+class StoreFacade {
+  constructor(storeDir) {
+    this.storeDir = storeDir;
+  }
+
+  _loadDir(dir) {
+    const full = path.join(this.storeDir, dir);
+    if (!fs.existsSync(full)) return [];
+    return fs.readdirSync(full)
+      .filter(f => f.endsWith('.json'))
+      .map(f => {
+        try { return JSON.parse(fs.readFileSync(path.join(full, f), 'utf8')); }
+        catch { return null; }
+      })
+      .filter(Boolean);
+  }
+
+  listSprints(filter = {}) {
+    return this._filterEntities(this._loadDir('sprints'), filter);
+  }
+
+  listTasks(filter = {}) {
+    return this._filterEntities(
+      this._loadDir('tasks').filter(e => e.taskId && !e.taskId.includes('BUG')),
+      filter
+    );
+  }
+
+  listBugs(filter = {}) {
+    return this._filterEntities(this._loadDir('bugs'), filter);
+  }
+
+  listFeatures(filter = {}) {
+    return this._filterEntities(this._loadDir('features'), filter);
+  }
+
+  getEntity(type, id) {
+    const dir = { tasks: 'tasks', bugs: 'bugs', sprints: 'sprints', features: 'features' }[type];
+    if (!dir) return null;
+    const filePath = path.join(this.storeDir, dir, `${id}.json`);
+    if (!fs.existsSync(filePath)) return null;
+    try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+    catch { return null; }
+  }
+
+  followFK(entity, fkField) {
+    const val = entity[fkField];
+    if (!val) return null;
+    const fkMap = {
+      sprintId:  'sprints',
+      featureId: 'features',
+      blockedBy: 'bugs',
+      blocksTask: 'tasks',
+      taskId:    'tasks',
+      bugId:     'bugs',
+    };
+    const targetType = fkMap[fkField];
+    if (!targetType) return null;
+    if (Array.isArray(val)) {
+      return val.map(v => this.getEntity(targetType, v)).filter(Boolean);
+    }
+    return this.getEntity(targetType, val);
+  }
+
+  _filterEntities(entities, filter) {
+    return entities.filter(e => {
+      for (const [key, val] of Object.entries(filter)) {
+        if (Array.isArray(val)) {
+          if (!val.includes(e[key])) return false;
+        } else if (e[key] !== val) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+}
+
+function extractExcerpt(indexPath, maxSentences = 4) {
+  if (!indexPath || !fs.existsSync(indexPath)) return null;
+  try {
+    const content = fs.readFileSync(indexPath, 'utf8');
+    const body = content.replace(/^---[\s\S]*?---\n*/, '');
+    const lines = body.split('\n')
+      .map(l => l.trim())
+      .filter(l =>
+        l &&
+        !l.startsWith('#') &&
+        !l.startsWith('<!--') &&
+        !l.startsWith('|') &&
+        !l.startsWith('---') &&
+        !l.startsWith('**Status**') &&
+        !l.startsWith('**Sprint**') &&
+        !l.startsWith('[Back to')
+      );
+    const text = lines.join(' ');
+    const sentences = text.match(/[^.!?]+[.!?]+/g) || [text];
+    return sentences.slice(0, maxSentences).join(' ').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+let _cfgCache = null;
+function loadForgeConfig(cwd) {
+  if (_cfgCache) return _cfgCache;
+  const root = cwd || process.cwd();
+  const configPath = path.join(root, '.forge', 'config.json');
+  let cfg = {};
+  if (fs.existsSync(configPath)) {
+    try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  }
+  const prefix = cfg.project?.prefix || 'WI';
+  const kbRel = cfg.paths?.engineering || 'engineering';
+  const storeRel = cfg.paths?.store || '.forge/store';
+  _cfgCache = {
+    prefix,
+    kbPath: fs.existsSync(path.join(root, kbRel)) ? kbRel : (fs.existsSync(path.join(root, 'engineering')) ? 'engineering' : null),
+    storePathRel: storeRel,
+    storePathAbs: path.join(root, storeRel),
+    projectName: cfg.project?.name || null,
+  };
+  return _cfgCache;
+}
+
+function resetConfigCache() {
+  _cfgCache = null;
+}
+
+function findIndexPath(entity, kbPath) {
+  if (entity.path) {
+    const p = entity.path.replace(/\/$/, '');
+    return `${p}/INDEX.md`;
+  }
+  if (!kbPath) return null;
+  if (entity.sprintId && !entity.taskId && !entity.bugId) {
+    return path.join(kbPath, 'sprints', entity.sprintId, 'INDEX.md');
+  }
+  if (entity.taskId) {
+    const match = entity.taskId.match(/-S(\d+)-/);
+    if (match) {
+      const taskNum = entity.taskId.split('-').pop().replace('T', 'task_');
+      return path.join(kbPath, 'sprints', `S${match[1]}`, 'tasks', taskNum, 'INDEX.md');
+    }
+  }
+  if (entity.bugId) {
+    const slug = entity.title
+      ? entity.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+$/, '')
+      : entity.bugId;
+    return path.join(kbPath, 'bugs', `${entity.bugId}-${slug}`, 'INDEX.md');
+  }
+  return null;
+}
+
+module.exports = { StoreFacade, extractExcerpt, loadForgeConfig, resetConfigCache, findIndexPath };

package/dist/forge-payload/.tools/lib/store-nlp.cjs

@@ -0,0 +1,250 @@
+'use strict';
+// store-nlp.cjs — deterministic rule-based NLP intent parser
+// No LLM, no network. Maps natural language to a traversal plan.
+
+const { loadForgeConfig } = require('./store-facade.cjs');
+
+const ENTITY_SYNONYMS = {
+  sprints:  ['sprint', 'sprints', 'release', 'releases', 'iteration', 'iterations'],
+  tasks:    ['task', 'tasks', 'item', 'items', 'work item', 'work items', 'todo', 'todos'],
+  bugs:     ['bug', 'bugs', 'defect', 'defects', 'issue', 'issues', 'problem', 'problems'],
+  features: ['feature', 'features', 'epic', 'epics', 'capability', 'capabilities'],
+};
+
+const STATUS_MAP = {
+  'open':         { tasks: 'planned', bugs: 'in-progress', sprints: 'active', features: 'active' },
+  'active':       { tasks: 'implementing', bugs: 'in-progress', sprints: 'active', features: 'active' },
+  'in progress':  { tasks: 'implementing', bugs: 'in-progress', sprints: 'active', features: 'active' },
+  'in-progress':  { tasks: 'implementing', bugs: 'in-progress', sprints: 'active', features: 'active' },
+  'completed':    { tasks: 'committed', bugs: 'fixed', sprints: 'completed', features: 'shipped' },
+  'done':         { tasks: 'committed', bugs: 'fixed', sprints: 'completed', features: 'shipped' },
+  'fixed':        { bugs: 'fixed' },
+  'planned':      { tasks: 'planned', sprints: 'planning' },
+  'planning':     { sprints: 'planning' },
+  'implementing': { tasks: 'implementing' },
+  'implemented':  { tasks: 'implemented' },
+  'committed':    { tasks: 'committed' },
+  'draft':        { tasks: 'draft', features: 'draft' },
+  'abandoned':    { tasks: 'abandoned', sprints: 'abandoned' },
+  'retired':      { features: 'retired' },
+  'shipped':      { features: 'shipped' },
+  'triaged':      { bugs: 'triaged' },
+  'reported':     { bugs: 'reported' },
+  'blocked':      { tasks: 'blocked' },
+  'critical':     { _field: 'severity', bugs: 'critical' },
+  'major':        { _field: 'severity', bugs: 'major' },
+  'minor':        { _field: 'severity', bugs: 'minor' },
+};
+
+const ALL_STOP_WORDS = new Set([
+  'list','all','the','show','find','what','which','are','in','for','about','related','to',
+  'of','and','with','details','status','how','many','there','a','an','is','that','this','on',
+  'by','me','give','get','tell','please','can','do','does','did','was','were','been','being',
+  'have','has','had','will','would','could','should','may','might',
+  'blocking','blocked','block','severity','titles','title',
+  ...Object.values(ENTITY_SYNONYMS).flat(),
+]);
+
+function idRegexes() {
+  const p = loadForgeConfig().prefix;
+  const esc = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return {
+    taskId: new RegExp(`\\b${esc}-S\\d+-T\\d+\\b`, 'i'),
+    bugId: new RegExp(`\\b${esc}-BUG-\\d+\\b`, 'i'),
+    taskIdAnchored: new RegExp(`^${esc}-S\\d+-T\\d+$`),
+    bugIdAnchored: new RegExp(`^${esc}-BUG-\\d+$`),
+  };
+}
+
+function parseIntentNLP(intent) {
+  const stripped = String(intent).replace(/^\s*forge[-_ ]?store\s*:?\s*/i, '');
+  const lower = stripped.toLowerCase().replace(/[^\w\s-]/g, ' ').replace(/\s+/g, ' ').trim();
+  const plan = {
+    traverse: {
+      primary: null,
+      filter: {},
+      follow: [],
+      keywordMatch: { field: 'title', terms: [] },
+    },
+  };
+
+  const consumed = new Set();
+  const _idRe = idRegexes();
+
+  // ── Stage 1: ID patterns ──
+  const idPatterns = [
+    { re: _idRe.taskId,       filter: 'taskId',    entity: 'tasks' },
+    { re: _idRe.bugId,        filter: 'bugId',     entity: 'bugs' },
+    { re: /\bFEAT-\d+\b/i,   filter: 'featureId', entity: null },
+    { re: /\bS\d+\b/i,        filter: 'sprintId',  entity: null },
+    { re: /sprint\s+(\d+)/i,  filter: 'sprintId',  entity: null, format: v => 'S' + v },
+  ];
+  let idEntityHint = null;
+  for (const { re, filter: filterKey, entity, format } of idPatterns) {
+    const m = lower.match(re);
+    if (m) {
+      const value = format ? format(m[1]) : m[0].toUpperCase();
+      plan.traverse.filter[filterKey] = value;
+      if (entity) idEntityHint = entity;
+      const words = lower.split(/\s+/);
+      const matchText = m[0].toLowerCase();
+      words.forEach((w, i) => { if (matchText.includes(w)) consumed.add(i); });
+      break;
+    }
+  }
+
+  // ── Stage 2: Entity detection ──
+  const words = lower.split(/\s+/);
+  let detectedEntity = null;
+  outer:
+  for (let i = 0; i < words.length; i++) {
+    if (consumed.has(i)) continue;
+    const w = words[i];
+    if (i + 1 < words.length) {
+      const bigram = w + ' ' + words[i + 1];
+      for (const [entity, synonyms] of Object.entries(ENTITY_SYNONYMS)) {
+        if (synonyms.includes(bigram)) {
+          detectedEntity = entity;
+          consumed.add(i);
+          consumed.add(i + 1);
+          break outer;
+        }
+      }
+    }
+    for (const [entity, synonyms] of Object.entries(ENTITY_SYNONYMS)) {
+      if (synonyms.includes(w)) {
+        detectedEntity = entity;
+        consumed.add(i);
+        break outer;
+      }
+    }
+  }
+
+  if (!detectedEntity && !idEntityHint && plan.traverse.filter.sprintId) {
+    plan.traverse.primary = 'sprints';
+  } else {
+    plan.traverse.primary = detectedEntity || idEntityHint || 'tasks';
+  }
+
+  // ── Stage 3: Status/severity filters ──
+  for (let i = 0; i < words.length; i++) {
+    if (consumed.has(i)) continue;
+    if (i + 1 < words.length) {
+      const bigram = words[i] + ' ' + words[i + 1];
+      if (STATUS_MAP[bigram]) {
+        const mapping = STATUS_MAP[bigram];
+        const field = mapping._field || 'status';
+        const value = mapping[plan.traverse.primary];
+        if (value) {
+          plan.traverse.filter[field] = value;
+          consumed.add(i);
+          consumed.add(i + 1);
+          continue;
+        }
+      }
+    }
+    const w = words[i];
+    if (STATUS_MAP[w]) {
+      const mapping = STATUS_MAP[w];
+      const field = mapping._field || 'status';
+      const value = mapping[plan.traverse.primary];
+      if (value) {
+        plan.traverse.filter[field] = value;
+        consumed.add(i);
+      }
+    }
+  }
+
+  // ── Stage 4: FK follow phrases ──
+  if (/\bwith\s+sprints?\b/.test(lower) || /\bsprint\s+for\b/.test(lower) || /\bwhich sprint\b/.test(lower)) {
+    if (!plan.traverse.follow.includes('sprintId')) plan.traverse.follow.push('sprintId');
+  }
+  if (/\bwith\s+features?\b/.test(lower) || /\bfeature\s+for\b/.test(lower)) {
+    if (!plan.traverse.follow.includes('featureId')) plan.traverse.follow.push('featureId');
+  }
+  if (/\bblock/i.test(lower) || /\bblocking\b/.test(lower)) {
+    if (plan.traverse.primary === 'bugs' && !plan.traverse.follow.includes('blockedBy')) {
+      plan.traverse.follow.push('blockedBy');
+    }
+    if (plan.traverse.primary === 'tasks' && !plan.traverse.follow.includes('blocksTask')) {
+      plan.traverse.follow.push('blocksTask');
+    }
+  }
+
+  // ── Stage 4b: Ordering / limit / count ──
+  let orderDir = null;
+  let limitN = null;
+  let countMode = false;
+
+  const biMap = [
+    { phrase: 'most recent', dir: 'desc', limit: 1 },
+    { phrase: 'how many',    count: true },
+    { phrase: 'count of',    count: true },
+    { phrase: 'number of',   count: true },
+  ];
+  for (let i = 0; i < words.length - 1; i++) {
+    if (consumed.has(i) || consumed.has(i + 1)) continue;
+    const bg = words[i] + ' ' + words[i + 1];
+    const hit = biMap.find(b => b.phrase === bg);
+    if (hit) {
+      if (hit.dir) orderDir = orderDir || hit.dir;
+      if (hit.limit && !limitN) limitN = hit.limit;
+      if (hit.count) countMode = true;
+      consumed.add(i); consumed.add(i + 1);
+    }
+  }
+
+  for (let i = 0; i < words.length; i++) {
+    if (consumed.has(i)) continue;
+    const w = words[i];
+    const next = words[i + 1];
+    const isNum = next && /^\d+$/.test(next);
+    if ((w === 'top' || w === 'first' || w === 'last') && isNum) {
+      limitN = parseInt(next, 10);
+      if (w === 'last') orderDir = orderDir || 'desc';
+      else orderDir = orderDir || (w === 'top' ? 'desc' : 'asc');
+      consumed.add(i); consumed.add(i + 1);
+      continue;
+    }
+    if (w === 'latest' || w === 'newest' || w === 'recent' || w === 'last') {
+      orderDir = orderDir || 'desc';
+      if (!limitN) limitN = 1;
+      consumed.add(i);
+    } else if (w === 'oldest' || w === 'earliest' || w === 'first') {
+      orderDir = orderDir || 'asc';
+      if (!limitN) limitN = 1;
+      consumed.add(i);
+    } else if (w === 'count') {
+      countMode = true;
+      consumed.add(i);
+    }
+  }
+
+  if (orderDir) plan.traverse.sort = orderDir;
+  if (limitN)   plan.traverse.limit = limitN;
+  if (countMode) plan.traverse.count = true;
+
+  // ── Stage 5: Keyword extraction ──
+  const keywords = words.filter(
+    (w, i) => !consumed.has(i) && w.length > 1 && !ALL_STOP_WORDS.has(w) && !/^\d+$/.test(w)
+  );
+  plan.traverse.keywordMatch.terms = [...new Set(keywords)];
+
+  return plan;
+}
+
+function extractKeywordsFromIntent(intent) {
+  const stopWords = new Set([
+    'list','all','the','show','find','what','which','are','in','for','about','related','to',
+    'of','and','with','sprints','tasks','bugs','features','details','status','open','closed',
+    'active','completed','how','many','there','a','an','is','that','this','on','by','me',
+    'give','get','tell','please','can','do','does','did','was','were','been','being',
+    'have','has','had','will','would','could','should','may','might',
+  ]);
+  return intent.toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/[\s-]+/)
+    .filter(w => w.length > 2 && !stopWords.has(w));
+}
+
+module.exports = { parseIntentNLP, extractKeywordsFromIntent, ENTITY_SYNONYMS, STATUS_MAP };

package/dist/forge-payload/.tools/lib/store-query-exec.cjs

@@ -0,0 +1,272 @@
+'use strict';
+// store-query-exec.cjs — query execution, result assembly, FK traversal
+
+const path = require('path');
+const { extractExcerpt, loadForgeConfig, findIndexPath } = require('./store-facade.cjs');
+const { extractKeywordsFromIntent } = require('./store-nlp.cjs');
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Word-boundary match. Prevents "store" matching "restore".
+function kwMatches(text, term) {
+  if (!term) return false;
+  const re = new RegExp(`(?:^|[^a-z0-9])${escapeRe(term.toLowerCase())}(?:$|[^a-z0-9])`, 'i');
+  return re.test(String(text || ''));
+}
+
+function sortKeyFor(entity, primary) {
+  const tail = s => { const m = String(s || '').match(/(\d+)$/); return m ? parseInt(m[1], 10) : 0; };
+  switch (primary) {
+    case 'sprints':  return tail(entity.sprintId);
+    case 'tasks':    return tail(entity.sprintId) * 10000 + tail(entity.taskId);
+    case 'bugs':     return tail(entity.bugId);
+    case 'features': return tail(entity.featureId || entity.feature_id);
+  }
+  return 0;
+}
+
+function buildResult(entity, type, store, includeExcerpts) {
+  const cfg = loadForgeConfig();
+  const idField = type === 'sprint' ? 'sprintId'
+    : type === 'task'    ? 'taskId'
+    : type === 'bug'     ? 'bugId'
+    : (entity.featureId ? 'featureId' : 'id');
+  const id = entity[idField] || 'unknown';
+
+  const result = {
+    id,
+    title: entity.title || entity.name || '',
+    status: entity.status || '',
+    type,
+    relationships: {},
+  };
+
+  if (entity.sprintId)                         result.relationships.sprintId  = entity.sprintId;
+  if (entity.featureId || entity.feature_id)   result.relationships.featureId = entity.featureId || entity.feature_id;
+  if (entity.blockedBy)                         result.relationships.blockedBy = entity.blockedBy;
+  if (entity.blocksTask)                        result.relationships.blocksTask = entity.blocksTask;
+
+  const pluralType = type === 'bug' ? 'bugs' : type === 'task' ? 'tasks' : type === 'sprint' ? 'sprints' : 'features';
+  const jsonPath = path.join(cfg.storePathRel, pluralType, `${id}.json`);
+  const mdPath = findIndexPath(entity, cfg.kbPath) || '';
+  result.fileRefs  = { json: jsonPath, md: mdPath };
+  result.storeRef  = jsonPath;
+  result.indexRef  = mdPath;
+  result.excerpt   = includeExcerpts ? extractExcerpt(mdPath) : null;
+
+  return result;
+}
+
+function buildFieldValidators() {
+  const { loadForgeConfig: cfg } = require('./store-facade.cjs');
+  const p = cfg().prefix;
+  const esc = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return {
+    sprints: {
+      sprintId: /^S\d+$/,
+      status: ['planning', 'active', 'completed', 'retrospective-done', 'blocked', 'partially-completed', 'abandoned'],
+    },
+    tasks: {
+      taskId:    new RegExp(`^${esc}-S\\d+-T\\d+$`),
+      sprintId:  /^S\d+$/,
+      featureId: /^FEAT-\d+$/,
+      status: ['draft', 'planned', 'plan-approved', 'implementing', 'implemented', 'review-approved', 'approved', 'committed', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+    },
+    bugs: {
+      bugId:    new RegExp(`^${esc}-BUG-\\d+$`),
+      sprintId: /^S\d+$/,
+      severity: ['critical', 'major', 'minor'],
+      status:   ['reported', 'triaged', 'in-progress', 'fixed', 'verified'],
+    },
+    features: {
+      featureId: /^FEAT-\d+$/,
+      status: ['active', 'draft', 'shipped', 'retired'],
+    },
+  };
+}
+
+function validatePlan(plan) {
+  const validators = buildFieldValidators();
+  const warnings = [];
+  let confidence = 'high';
+  const traverse = plan.traverse || plan;
+  const singMap = { bug: 'bugs', task: 'tasks', sprint: 'sprints', feature: 'features' };
+  const primary = singMap[traverse.primary] || traverse.primary;
+  const valid = new Set(['tasks', 'bugs', 'sprints', 'features', ...Object.keys(singMap)]);
+
+  if (!valid.has(primary)) {
+    warnings.push(`invalid primary "${traverse.primary}"`);
+    confidence = 'low';
+  }
+
+  const fields = validators[primary];
+  const filter = traverse.filter || {};
+  if (fields) {
+    for (const [key, val] of Object.entries(filter)) {
+      if (!fields[key]) {
+        warnings.push(`invalid filter key "${key}" for ${primary}`);
+        confidence = 'low';
+      } else if (fields[key] instanceof RegExp) {
+        if (!fields[key].test(String(val))) {
+          warnings.push(`filter ${key}="${val}" does not match pattern`);
+          confidence = 'low';
+        }
+      } else if (Array.isArray(fields[key])) {
+        if (!fields[key].includes(String(val))) {
+          warnings.push(`filter ${key}="${val}" not in enum`);
+          confidence = 'low';
+        }
+      }
+    }
+  }
+  return { confidence, warnings };
+}
+
+function executeQuery(plan, store, cfg) {
+  const trace = [];
+  const traverse = plan.traverse || plan;
+  const singMap = { bug: 'bugs', task: 'tasks', sprint: 'sprints', feature: 'features' };
+  const primary = singMap[traverse.primary] || traverse.primary || 'tasks';
+  let filter = { ...(traverse.filter || {}) };
+  const follow = traverse.follow || [];
+  const kwMatch = traverse.keywordMatch || {};
+  const includeExcerpts = cfg.noExcerpts !== true;
+
+  trace.push('intent parsed via NLP rules');
+
+  // Validate + strip invalid filters
+  const validation = validatePlan(plan);
+  if (validation.warnings.length > 0) {
+    const validators = buildFieldValidators();
+    const fields = validators[primary];
+    if (fields) {
+      for (const key of Object.keys(filter)) {
+        if (!fields[key]) {
+          trace.push(`stripped invalid filter key: ${key}`);
+          delete filter[key];
+        } else {
+          const spec = fields[key];
+          if (spec instanceof RegExp && !spec.test(String(filter[key]))) {
+            trace.push(`stripped filter ${key}="${filter[key]}" (value mismatch)`);
+            delete filter[key];
+          } else if (Array.isArray(spec) && !spec.includes(String(filter[key]))) {
+            trace.push(`stripped filter ${key}="${filter[key]}" (not in enum)`);
+            delete filter[key];
+          }
+        }
+      }
+    }
+  }
+
+  // List primary entities
+  let entities;
+  switch (primary) {
+    case 'sprints':  entities = store.listSprints(filter);  break;
+    case 'tasks':    entities = store.listTasks(filter);    break;
+    case 'bugs':     entities = store.listBugs(filter);     break;
+    case 'features': entities = store.listFeatures(filter); break;
+    default:         entities = [];
+  }
+
+  // Keyword filter
+  const hasMeaningfulKw = kwMatch.field && kwMatch.terms && kwMatch.terms.length > 0
+    && !kwMatch.terms.some(t => t.length > 20);
+  if (hasMeaningfulKw) {
+    const before = entities.length;
+    entities = entities.filter(e => kwMatch.terms.some(t => kwMatches(e[kwMatch.field] || '', t)));
+    trace.push(`keyword matched ${kwMatch.terms.join(', ')} on ${kwMatch.field}: ${before} → ${entities.length}`);
+  } else if (Object.keys(filter).length > 0) {
+    trace.push(`listed ${primary} with filter ${JSON.stringify(filter)}: ${entities.length} results`);
+  } else {
+    trace.push(`listed ${primary}: ${entities.length} results`);
+  }
+
+  const totalMatched = entities.length;
+
+  // Sort
+  if (traverse.sort) {
+    entities.sort((a, b) => {
+      const ka = sortKeyFor(a, primary);
+      const kb = sortKeyFor(b, primary);
+      return traverse.sort === 'desc' ? kb - ka : ka - kb;
+    });
+    trace.push(`sorted ${primary} ${traverse.sort}`);
+  }
+
+  // Count mode
+  if (traverse.count) {
+    trace.push(`count mode: ${totalMatched}`);
+    return { query: cfg.query || '', path: 'intent-nlp', traversalTrace: trace, count: totalMatched, results: [], relatedFileRefs: [], totalMatched };
+  }
+
+  // Limit
+  if (traverse.limit && entities.length > traverse.limit) {
+    trace.push(`limited to ${traverse.limit} (of ${totalMatched})`);
+    entities = entities.slice(0, traverse.limit);
+  }
+
+  // Build results + follow FKs
+  const allResults = [];
+  const relatedFiles = [];
+  const singType = primary.replace(/s$/, '');
+
+  for (const entity of entities) {
+    allResults.push(buildResult(entity, singType, store, includeExcerpts));
+    for (const fk of follow) {
+      const related = store.followFK(entity, fk);
+      if (related) {
+        const relatedList = Array.isArray(related) ? related : [related];
+        const fkSingType = fk.replace(/Id$/, '').replace(/s$/, '');
+        for (const r of relatedList) {
+          allResults.push(buildResult(r, fkSingType, store, includeExcerpts));
+        }
+        trace.push(`followed ${fk} → ${relatedList.length} related`);
+      }
+    }
+  }
+
+  for (const r of allResults) {
+    if (r.fileRefs?.md) relatedFiles.push(r.fileRefs.md);
+    if (r.fileRefs?.json) relatedFiles.push(r.fileRefs.json);
+  }
+
+  trace.push(`plan confidence: ${validation.confidence}`);
+
+  // Auto-retry on zero results
+  if (allResults.length === 0 && (Object.keys(filter).length > 0 || hasMeaningfulKw)) {
+    trace.push('0 results — retrying with title-only keyword search');
+    const retryTerms = extractKeywordsFromIntent(cfg.query || '');
+    if (retryTerms.length > 0) {
+      let retryEntities;
+      switch (primary) {
+        case 'sprints':  retryEntities = store.listSprints({});  break;
+        case 'tasks':    retryEntities = store.listTasks({});    break;
+        case 'bugs':     retryEntities = store.listBugs({});     break;
+        case 'features': retryEntities = store.listFeatures({}); break;
+        default:         retryEntities = [];
+      }
+      retryEntities = retryEntities.filter(e => retryTerms.some(t => kwMatches(e.title || '', t)));
+      trace.push(`retry: keyword "${retryTerms.join(', ')}" in ${primary}: ${retryEntities.length} results`);
+      for (const entity of retryEntities) {
+        allResults.push(buildResult(entity, singType, store, includeExcerpts));
+      }
+      if (allResults.length > 0) trace.push('overall confidence: low (required retry)');
+    }
+  }
+
+  return {
+    query:          cfg.query || '',
+    path:           'intent-nlp',
+    traversalTrace: trace,
+    results:        allResults,
+    totalMatched,
+    returned:       allResults.length,
+    limit:          traverse.limit || null,
+    sort:           traverse.sort || null,
+    relatedFileRefs: [...new Set(relatedFiles)],
+  };
+}
+
+module.exports = { executeQuery, buildResult, kwMatches };