@entelligentsia/forgecli 0.8.4 → 0.9.0

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

@@ -1,162 +0,0 @@
-'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

@@ -1,250 +0,0 @@
-'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

@@ -1,272 +0,0 @@
-'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 };