@dotdotgod/cli 0.1.35 → 0.1.36

package/src/index/cache.mjs

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseCommon } from '../cli/usage.mjs';
+import { rel } from '../common/paths.mjs';
+import { readMemoryConfig, memoryConfigSummary } from '../memory/config.mjs';
+import { addEdge, addNode, compactGraph, expandGraph, graphStats, jsonSize, shardFile, writeJson } from '../graph/store.mjs';
+import { cacheFile, collectIndexFiles, fingerprint } from './files.mjs';
+import { CACHE_VERSION } from './constants.mjs';
+import { buildGraph } from '../graph/extract.mjs';
+import { addDeterministicSemanticEdges } from '../graph/semantic.mjs';
+
+function collectFingerprints(root, config = readMemoryConfig(root)) {
+  return collectIndexFiles(root, config).map((file) => {
+    const stats = statSync(file);
+    return { path: rel(root, file), sha256: fingerprint(file), size: stats.size, mtimeMs: Math.round(stats.mtimeMs) };
+  });
+}
+
+function nodeOwnedByPath(node, paths) {
+  return paths.has(node.path) || paths.has(node.id?.replace(/^file:/, '')) || paths.has(node.id?.replace(/^test:/, ''));
+}
+
+function mergeIncrementalGraph(previousGraph, changedGraph, changedPaths) {
+  if (!previousGraph) return changedGraph;
+  const changedSet = new Set(changedPaths);
+  const changedNodeIds = new Set(previousGraph.nodes.filter((node) => nodeOwnedByPath(node, changedSet)).map((node) => node.id));
+  for (const node of changedGraph.nodes) changedNodeIds.add(node.id);
+  const graph = { nodes: [], edges: [] };
+  for (const node of previousGraph.nodes) if (!changedNodeIds.has(node.id) && !nodeOwnedByPath(node, changedSet)) addNode(graph, node.id, node.type, Object.fromEntries(Object.entries(node).filter(([key]) => key !== 'id' && key !== 'type')));
+  for (const edge of previousGraph.edges) if (!changedNodeIds.has(edge.source) && !changedNodeIds.has(edge.target)) addEdge(graph, edge.source, edge.target, edge.relation, Object.fromEntries(Object.entries(edge).filter(([key]) => key !== 'source' && key !== 'target' && key !== 'relation')));
+  for (const node of changedGraph.nodes) addNode(graph, node.id, node.type, Object.fromEntries(Object.entries(node).filter(([key]) => key !== 'id' && key !== 'type')));
+  for (const edge of changedGraph.edges) addEdge(graph, edge.source, edge.target, edge.relation, Object.fromEntries(Object.entries(edge).filter(([key]) => key !== 'source' && key !== 'target' && key !== 'relation')));
+  return graph;
+}
+
+export function buildIndex(root, previous = readIndex(root)) {
+  const startedAt = Date.now();
+  const memoryConfig = readMemoryConfig(root);
+  const files = collectFingerprints(root, memoryConfig);
+  const indexed = new Map((previous?.files ?? []).map((file) => [file.path, file.sha256]));
+  const currentPaths = new Set(files.map((file) => file.path));
+  const removedPaths = (previous?.files ?? []).filter((file) => !currentPaths.has(file.path)).map((file) => file.path);
+  const changedPaths = [...files.filter((file) => indexed.get(file.path) !== file.sha256).map((file) => file.path), ...removedPaths];
+  const changedFiles = files.filter((file) => changedPaths.includes(file.path)).map((file) => join(root, file.path));
+  const fullRebuild = !previous?.graph || previous.version !== CACHE_VERSION;
+  const refreshReason = !previous ? 'missing' : previous.version !== CACHE_VERSION ? 'schema-mismatch' : removedPaths.length > 0 ? 'content-removed' : changedPaths.length > 0 ? 'content-changed' : 'fresh';
+  const rawGraph = fullRebuild ? buildGraph(root, files.map((file) => join(root, file.path)), memoryConfig) : mergeIncrementalGraph(previous.graph, buildGraph(root, changedFiles, memoryConfig), changedPaths);
+  const graph = addDeterministicSemanticEdges(rawGraph, memoryConfig);
+  const archiveBodiesIncluded = (memoryConfig.areas ?? []).some((area) => area.id === 'archive-body' && area.includeBodiesByDefault !== false);
+  return { version: CACHE_VERSION, schemaVersion: CACHE_VERSION, generatedAt: new Date().toISOString(), archiveBodiesIncluded, memoryConfig: memoryConfigSummary(memoryConfig), files, graph, stats: graphStats(graph), incremental: { enabled: true, fullRebuild, changedFiles: changedPaths.length, refreshReason, elapsedMs: Date.now() - startedAt } };
+}
+
+export function writeIndex(root, index) {
+  const compact = compactGraph(index.graph);
+  for (const [name, rows] of Object.entries(compact.nodes)) writeJson(shardFile(root, 'nodes', name), rows);
+  for (const [name, rows] of Object.entries(compact.edges)) writeJson(shardFile(root, 'edges', name), rows);
+  const graphShards = { nodes: Object.fromEntries(Object.keys(compact.nodes).map((name) => [name, rel(root, shardFile(root, 'nodes', name))])), edges: Object.fromEntries(Object.keys(compact.edges).map((name) => [name, rel(root, shardFile(root, 'edges', name))])) };
+  const manifest = { version: index.version, schemaVersion: index.schemaVersion ?? index.version, generatedAt: index.generatedAt, archiveBodiesIncluded: index.archiveBodiesIncluded, memoryConfig: index.memoryConfig, files: index.files, graph: { ...graphStats(index.graph), compactSchema: true, shards: graphShards }, incremental: index.incremental };
+  writeJson(cacheFile(root), manifest);
+  const shardBytes = [...Object.values(graphShards.nodes), ...Object.values(graphShards.edges)].reduce((sum, path) => sum + jsonSize(join(root, path)), 0);
+  const manifestBytes = jsonSize(cacheFile(root));
+  return { ...manifest, indexSizeBytes: manifestBytes + shardBytes, manifestBytes, shardBytes };
+}
+
+export function readIndex(root) {
+  const file = cacheFile(root);
+  if (!existsSync(file)) return null;
+  try {
+    const manifest = JSON.parse(readFileSync(file, 'utf8'));
+    const shards = manifest.graph?.shards;
+    if (!shards) return manifest;
+    const compact = { nodes: {}, edges: {} };
+    for (const [name, path] of Object.entries(shards.nodes ?? {})) compact.nodes[name] = existsSync(join(root, path)) ? JSON.parse(readFileSync(join(root, path), 'utf8')) : [];
+    for (const [name, path] of Object.entries(shards.edges ?? {})) compact.edges[name] = existsSync(join(root, path)) ? JSON.parse(readFileSync(join(root, path), 'utf8')) : [];
+    return { ...manifest, graph: expandGraph(compact) };
+  } catch { return null; }
+}
+
+export function getStatus(root) {
+  const index = readIndex(root);
+  const memoryConfig = readMemoryConfig(root);
+  const currentFiles = collectFingerprints(root, memoryConfig);
+  if (!index) return { ok: false, status: 'missing', cachePath: rel(root, cacheFile(root)), indexedFiles: 0, currentFiles: currentFiles.length, staleFiles: currentFiles.length, archiveBodiesIncluded: false, schemaVersion: null, expectedSchemaVersion: CACHE_VERSION, schemaOk: false, reason: 'missing' };
+  const indexed = new Map((index.files ?? []).map((file) => [file.path, file.sha256]));
+  const currentMap = new Map(currentFiles.map((file) => [file.path, file.sha256]));
+  const stale = currentFiles.filter((file) => indexed.get(file.path) !== file.sha256).map((file) => file.path);
+  const removed = [...indexed.keys()].filter((path) => !currentMap.has(path));
+  const staleFiles = [...stale, ...removed];
+  const schemaVersion = index.schemaVersion ?? index.version ?? null;
+  const schemaOk = schemaVersion === CACHE_VERSION;
+  const ok = staleFiles.length === 0 && schemaOk;
+  const reason = ok ? 'fresh' : !schemaOk ? 'schema-mismatch' : staleFiles.length > 0 ? 'content-changed' : 'unknown';
+  return { ok, status: ok ? 'fresh' : 'stale', cachePath: rel(root, cacheFile(root)), indexedFiles: index.files?.length ?? 0, currentFiles: currentFiles.length, staleFiles: staleFiles.length, examples: staleFiles.slice(0, 10), archiveBodiesIncluded: index.archiveBodiesIncluded === true, schemaVersion, expectedSchemaVersion: CACHE_VERSION, schemaOk, reason, graph: graphStats(index.graph ?? { nodes: [], edges: [] }) };
+}
+
+export function runIndex(argv) {
+  const options = parseCommon(argv);
+  const index = buildIndex(options.root);
+  const manifest = writeIndex(options.root, index);
+  const result = { ok: true, cachePath: rel(options.root, cacheFile(options.root)), schemaVersion: CACHE_VERSION, indexedFiles: index.files.length, nodes: index.graph.nodes.length, edges: index.graph.edges.length, indexSizeBytes: manifest.indexSizeBytes, shards: manifest.graph.shards, incremental: index.incremental, archiveBodiesIncluded: index.archiveBodiesIncluded === true, memoryConfig: index.memoryConfig };
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(`✅ index written (${result.indexedFiles} files, ${result.nodes} nodes, ${result.edges} edges, ${(result.indexSizeBytes / 1024).toFixed(1)} KiB, cache: ${result.cachePath})`);
+}
+
+export function runStatus(argv) {
+  const options = parseCommon(argv);
+  const status = getStatus(options.root);
+  if (options.json) console.log(JSON.stringify(status, null, 2));
+  else console.log(`dotdotgod index status: ${status.status} (${status.indexedFiles}/${status.currentFiles} files, cache: ${status.cachePath})`);
+  process.exit(status.ok ? 0 : 1);
+}
+
+export function readFreshIndex(root) {
+  const startedAt = Date.now();
+  const initialStatus = getStatus(root);
+  if (initialStatus.ok) return { status: initialStatus, index: readIndex(root), metadata: { cacheRefreshed: false, elapsedMs: Date.now() - startedAt, refreshReason: 'fresh', schemaVersion: CACHE_VERSION } };
+  const index = buildIndex(root);
+  const manifest = writeIndex(root, index);
+  const status = getStatus(root);
+  return { status, index, metadata: { cacheRefreshed: true, previousStatus: initialStatus.status, previousReason: initialStatus.reason, refreshReason: index.incremental?.refreshReason ?? initialStatus.reason, changedFiles: index.incremental?.changedFiles ?? initialStatus.staleFiles, fullRebuild: index.incremental?.fullRebuild === true, indexedFiles: index.files.length, indexSizeBytes: manifest.indexSizeBytes, manifestBytes: manifest.manifestBytes, shardBytes: manifest.shardBytes, elapsedMs: Date.now() - startedAt, indexElapsedMs: index.incremental?.elapsedMs, schemaVersion: CACHE_VERSION, archiveBodiesIncluded: index.archiveBodiesIncluded === true } };
+}
+
+export function graphSummary(index) {
+  const graph = index?.graph ?? { nodes: [], edges: [] };
+  const byType = graph.nodes.reduce((acc, node) => ({ ...acc, [node.type]: (acc[node.type] ?? 0) + 1 }), {});
+  const byRelation = graph.edges.reduce((acc, edge) => ({ ...acc, [edge.relation]: (acc[edge.relation] ?? 0) + 1 }), {});
+  return { nodes: graph.nodes.length, edges: graph.edges.length, byType, byRelation };
+}

package/src/index/constants.mjs

@@ -0,0 +1,3 @@
+export const CACHE_VERSION = 11;
+export const CACHE_DIR = '.dotdotgod';
+export const MANIFEST_FILE = 'manifest.json';

package/src/memory/config.mjs

@@ -13,6 +13,9 @@ export const DEFAULT_TRACEABILITY_POLICY = {
 export const DEFAULT_VALIDATION_POLICY = {
   markdown: { maxLines: 200, maxChars: 10000, exclude: [] },
 };
+export const DEFAULT_INTEGRATIONS_POLICY = {
+  trello: { syncPaths: [] },
+};
 export const DEFAULT_IMPACT_RANKING_POLICY = {
   preset: 'balanced',
   weights: { ppr: 40, traceability: 30, memoryPolicy: 10, verification: 15, proximity: 10, semantic: 10, freshness: 5, archivePenalty: -25 },
@@ -151,15 +154,19 @@ function normalizeImpactRankingPolicy(raw) {
   return cloneImpactRankingPolicy({ ...preset, ...raw, preset: presetName, weights: { ...(preset.weights ?? {}), ...(raw?.weights ?? {}) }, ppr: { ...(preset.ppr ?? {}), ...(raw?.ppr ?? {}) }, semantic: { ...(preset.semantic ?? {}), ...(raw?.semantic ?? {}) } });
 }
 
+export function cloneIntegrationsPolicy(policy = DEFAULT_INTEGRATIONS_POLICY) {
+  return { trello: { syncPaths: [...(policy.trello?.syncPaths ?? [])] } };
+}
+
 export function defaultMemoryConfig() {
-  return { source: 'default', areas: DEFAULT_MEMORY_AREAS.map(cloneArea), traceability: cloneTraceabilityPolicy(), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy() };
+  return { source: 'default', areas: DEFAULT_MEMORY_AREAS.map(cloneArea), traceability: cloneTraceabilityPolicy(), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy(), integrations: cloneIntegrationsPolicy() };
 }
 
-function normalizePathPattern(value = '') {
+export function normalizePathPattern(value = '') {
   return value.replaceAll('\\', '/').replace(/^\.\//, '').replace(/\/+$|^\/+/, '');
 }
 
-function isValidPathPattern(value) {
+export function isValidPathPattern(value) {
   if (typeof value !== 'string' || !value.trim()) return false;
   const normalized = normalizePathPattern(value);
   if (!normalized || normalized.startsWith('../') || normalized.includes('/../') || normalized === '..') return false;
@@ -167,7 +174,7 @@ function isValidPathPattern(value) {
   return true;
 }
 
-function matchMemoryPattern(path, pattern) {
+export function matchPathPattern(path, pattern) {
   const normalized = normalizePathPattern(path);
   const normalizedPattern = normalizePathPattern(pattern);
   if (normalizedPattern.endsWith('/**')) {
@@ -182,9 +189,9 @@ function matchMemoryPattern(path, pattern) {
 }
 
 function areaMatchesPath(area, path) {
-  const excluded = (area.excludePaths ?? []).some((pattern) => matchMemoryPattern(path, pattern));
+  const excluded = (area.excludePaths ?? []).some((pattern) => matchPathPattern(path, pattern));
   if (excluded) return false;
-  return (area.paths ?? []).some((pattern) => matchMemoryPattern(path, pattern));
+  return (area.paths ?? []).some((pattern) => matchPathPattern(path, pattern));
 }
 
 export function resolveMemoryArea(path = '', config = defaultMemoryConfig()) {
@@ -223,16 +230,31 @@ function normalizeValidationPolicy(raw) {
   });
 }
 
+function normalizeIntegrationsPolicy(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return cloneIntegrationsPolicy();
+  const syncPaths = Array.isArray(raw.trello?.syncPaths) ? raw.trello.syncPaths.map(normalizePathPattern) : [];
+  return cloneIntegrationsPolicy({ trello: { syncPaths: [...new Set(syncPaths)] } });
+}
+
+function isSecretLikePathPattern(value = '') {
+  const normalized = normalizePathPattern(value);
+  return /(^|\/)(\.env|\.npmrc|\.pypirc|id_rsa|id_dsa|id_ed25519|credentials?|secrets?)(\.|\/|$)/i.test(normalized);
+}
+
+export function trelloSyncPaths(config = defaultMemoryConfig()) {
+  return [...new Set(['docs/trello/**', ...((config.integrations ?? DEFAULT_INTEGRATIONS_POLICY).trello?.syncPaths ?? [])])];
+}
+
 export function isMarkdownSizeExcluded(path = '', config = defaultMemoryConfig()) {
   const policy = config.validation ?? DEFAULT_VALIDATION_POLICY;
-  return (policy.markdown?.exclude ?? []).some((pattern) => matchMemoryPattern(path, pattern));
+  return (policy.markdown?.exclude ?? []).some((pattern) => matchPathPattern(path, pattern));
 }
 
 export function requiresTraceability(path = '', config = defaultMemoryConfig()) {
   const policy = config.traceability ?? DEFAULT_TRACEABILITY_POLICY;
-  const excluded = (policy.exclude ?? []).some((pattern) => matchMemoryPattern(path, pattern));
+  const excluded = (policy.exclude ?? []).some((pattern) => matchPathPattern(path, pattern));
   if (excluded) return false;
-  return (policy.required ?? []).some((pattern) => matchMemoryPattern(path, pattern));
+  return (policy.required ?? []).some((pattern) => matchPathPattern(path, pattern));
 }
 
 function normalizeMemoryArea(raw) {
@@ -295,6 +317,23 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
       }
     }
   }
+  const integrations = data.integrations;
+  if (integrations !== undefined) {
+    if (!integrations || typeof integrations !== 'object' || Array.isArray(integrations)) {
+      add('INTEGRATIONS_CONFIG_INVALID', 'integrations', 'Expected an object.');
+    } else if (integrations.trello !== undefined) {
+      const trello = integrations.trello;
+      if (!trello || typeof trello !== 'object' || Array.isArray(trello)) {
+        add('INTEGRATIONS_TRELLO_CONFIG_INVALID', 'integrations.trello', 'Expected an object.');
+      } else if (trello.syncPaths !== undefined) {
+        if (!Array.isArray(trello.syncPaths)) add('INTEGRATIONS_TRELLO_INVALID_SYNC_PATHS', 'integrations.trello.syncPaths', 'Expected an array of path strings.');
+        else {
+          if (trello.syncPaths.some((value) => !isValidPathPattern(value) || (typeof value === 'string' && value.trim().startsWith('/')))) add('INTEGRATIONS_TRELLO_INVALID_SYNC_PATHS', 'integrations.trello.syncPaths', 'Expected repository-relative path strings using exact paths, /** subtree patterns, or **/suffix patterns.');
+          if (trello.syncPaths.some((value) => typeof value === 'string' && isSecretLikePathPattern(value))) add('INTEGRATIONS_TRELLO_SECRET_SYNC_PATH', 'integrations.trello.syncPaths', 'Sync paths must not target secrets, credentials, environment files, or private keys.');
+        }
+      }
+    }
+  }
   const referenceExpansion = data.referenceExpansion;
   if (referenceExpansion !== undefined) {
     if (!referenceExpansion || typeof referenceExpansion !== 'object' || Array.isArray(referenceExpansion)) {
@@ -405,7 +444,8 @@ export function readMemoryConfig(root = '.') {
       const validation = data.validation === undefined ? cloneValidationPolicy() : normalizeValidationPolicy(data.validation);
       const impactRanking = normalizeImpactRankingPolicy(data.impactRanking);
       const referenceExpansion = normalizeReferenceExpansionPolicy(data.referenceExpansion);
-      return configuredAreas.length > 0 ? { source: name, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, source: name, errors: [] };
+      const integrations = normalizeIntegrationsPolicy(data.integrations);
+      return configuredAreas.length > 0 ? { source: name, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, integrations, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, integrations, source: name, errors: [] };
     } catch (error) {
       return { ...defaultMemoryConfig(), source: name, errors: [{ file: name, code: 'MEMORY_CONFIG_INVALID_JSON', message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}\nFix: repair ${name} so it is valid JSON, or regenerate the default config with \`dotdotgod config init <root> --force\` if you want to reset it.` }] };
     }
@@ -437,6 +477,7 @@ export function defaultDotdotgodConfigData() {
     validation: cloneValidationPolicy(config.validation),
     impactRanking: cloneImpactRankingPolicy(config.impactRanking),
     referenceExpansion: { fuzzy: { lowSignal: { add: [], remove: [] } } },
+    integrations: cloneIntegrationsPolicy(config.integrations),
   };
 }
 
@@ -462,6 +503,7 @@ export function memoryConfigSummary(config) {
     validation: cloneValidationPolicy(config.validation ?? DEFAULT_VALIDATION_POLICY),
     impactRanking: cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY),
     referenceExpansion: cloneReferenceExpansionPolicy(config.referenceExpansion),
+    integrations: cloneIntegrationsPolicy(config.integrations),
   };
 }
 

package/src/reference/extract.mjs

@@ -0,0 +1,135 @@
+import { basename, dirname, extname } from 'node:path';
+import { cloneReferenceExpansionPolicy, defaultMemoryConfig, normalizeLowSignalTerm } from '../memory/config.mjs';
+
+export const DEFAULT_REFERENCE_LIMIT = 5;
+
+export function extractBracketReferences(prompt = '') {
+  const refs = [];
+  const seen = new Set();
+  for (const match of String(prompt).matchAll(/\[\[([^\]]+)\]\]/g)) {
+    const raw = match[1].trim();
+    if (!raw) continue;
+    const target = raw.split('|')[0].trim();
+    if (!target || seen.has(target)) continue;
+    seen.add(target);
+    refs.push({ raw: match[0], target, label: raw.includes('|') ? raw.split('|').slice(1).join('|').trim() : undefined });
+  }
+  return refs;
+}
+
+function fuzzyLowSignalSet(policy = defaultMemoryConfig().referenceExpansion) {
+  return new Set(cloneReferenceExpansionPolicy(policy).fuzzy.lowSignal.terms);
+}
+
+function fuzzyPhraseAllowed(value = '', lowSignalTerms = fuzzyLowSignalSet()) {
+  const normalized = normalizeLowSignalTerm(value);
+  if (normalized.length < 3) return false;
+  if (lowSignalTerms.has(normalized)) return false;
+  return /[a-z0-9가-힣]/i.test(normalized);
+}
+
+function fuzzyTokenKey(value = '') {
+  return String(value).trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+export function normalizeReferenceAlias(value = '') {
+  return String(value)
+    .trim()
+    .replace(/^\[\[/, '')
+    .replace(/\]\]$/, '')
+    .split('|')[0]
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\.md$/i, '')
+    .toLowerCase()
+    .replace(/[\s_-]+/g, '')
+    .replace(/[^a-z0-9/#.]/g, '');
+}
+
+export function referencePathForNode(node) {
+  if (node?.path) return node.path;
+  if (typeof node?.id === 'string' && node.id.startsWith('file:')) return node.id.slice(5);
+  if (typeof node?.id === 'string' && node.id.startsWith('heading:')) return node.id.slice(8).split('#')[0];
+  return '';
+}
+
+export function isArchiveBodyPath(path = '') {
+  return path.startsWith('docs/archive/') && path !== 'docs/archive/README.md';
+}
+
+function aliasEntriesForPath(path = '') {
+  const entries = [];
+  const base = basename(path);
+  const ext = extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  const withoutMd = path.replace(/\.md$/i, '');
+  const parts = withoutMd.split('/').filter(Boolean);
+  for (let i = 0; i < parts.length; i += 1) entries.push({ alias: parts.slice(i).join('/'), kind: 'path-suffix' });
+  if (base === 'README.md') {
+    const dir = dirname(path).replace(/\\/g, '/');
+    entries.push({ alias: basename(dir), kind: 'path' });
+  }
+  for (const alias of [path, withoutMd, base, stem]) entries.push({ alias, kind: 'path' });
+  return entries.filter((entry) => entry.alias);
+}
+
+export function referenceCandidateAliases(node) {
+  const path = referencePathForNode(node);
+  const entries = [];
+  if (node.type === 'file' && path) entries.push(...aliasEntriesForPath(path));
+  if (node.type === 'heading') {
+    const fileStem = path ? basename(path, extname(path)) : '';
+    const anchor = typeof node.id === 'string' && node.id.includes('#') ? node.id.split('#').pop() : '';
+    for (const alias of [node.title, anchor, fileStem && node.title ? `${fileStem}#${node.title}` : '', fileStem && anchor ? `${fileStem}#${anchor}` : '', path && node.title ? `${path}#${node.title}` : '', path && anchor ? `${path}#${anchor}` : '']) entries.push({ alias, kind: 'heading' });
+  }
+  return entries.filter((entry) => entry.alias);
+}
+
+export function extractFuzzyReferences(prompt = '', index = null, options = {}) {
+  const text = String(prompt ?? '');
+  const masked = text.replace(/\[\[[^\]\n]+\]\]/g, ' ');
+  const seen = new Set((options.existingTargets ?? []).map((value) => fuzzyTokenKey(value)));
+  const lowSignalTerms = fuzzyLowSignalSet(options.referenceExpansion ?? options.memoryConfig?.referenceExpansion ?? index?.memoryConfig?.referenceExpansion);
+  const refs = [];
+  const add = (target, reason, confidence = 'medium') => {
+    const clean = String(target ?? '').trim().replace(/^['"`]+|['"`]+$/g, '').replace(/\s+/g, ' ');
+    if (!fuzzyPhraseAllowed(clean, lowSignalTerms)) return;
+    const key = fuzzyTokenKey(clean);
+    if (seen.has(key)) return;
+    seen.add(key);
+    refs.push({ raw: clean, target: clean, source: 'fuzzy', confidence, reasons: [reason] });
+  };
+
+  for (const match of masked.matchAll(/(?:^|\s)([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+(?:#[A-Za-z0-9 _-]+)?|[A-Z0-9]{3,})(?=$|\s|[.,:;!?])/g)) add(match[1], 'uppercase_identifier', 'high');
+  for (const match of masked.matchAll(/(?:^|\s)((?:\.?\/?(?:docs|packages|src|test|spec|arch|plan|archive)\/)?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+(?:\.md)?(?:#[A-Za-z0-9 _-]+)?)(?=$|\s|[.,:;!?])/g)) add(match[1].replace(/^\.\//, ''), 'path_like', 'high');
+  for (const match of masked.matchAll(/[`"']([^`"'\n]{4,80})[`"']/g)) add(match[1], 'quoted_phrase', 'medium');
+
+  const graph = index?.graph ?? null;
+  if (graph) {
+    const lower = ` ${masked.toLowerCase().replace(/[^a-z0-9가-힣/#._-]+/gi, ' ')} `;
+    const aliasByKey = new Map();
+    for (const node of graph.nodes ?? []) {
+      if (!['file', 'heading'].includes(node.type)) continue;
+      const path = referencePathForNode(node);
+      if (options.includeArchive !== true && isArchiveBodyPath(path)) continue;
+      for (const entry of referenceCandidateAliases(node)) {
+        const alias = String(entry.alias ?? '').replace(/\.md$/i, '').replace(/[_-]+/g, ' ').trim();
+        if (!fuzzyPhraseAllowed(alias, lowSignalTerms)) continue;
+        const words = alias.split(/[\s/]+/).filter(Boolean);
+        if (words.length > 3 || words.some((word) => lowSignalTerms.has(normalizeLowSignalTerm(word)))) continue;
+        const key = fuzzyTokenKey(alias);
+        const previous = aliasByKey.get(key);
+        const priority = Number(node.retrievalPriority ?? node.retrieval?.priority ?? 30);
+        if (!previous || priority > previous.priority) aliasByKey.set(key, { alias, priority });
+      }
+    }
+    for (const { alias } of [...aliasByKey.values()].sort((a, b) => b.priority - a.priority || b.alias.length - a.alias.length)) {
+      const escaped = alias.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '[\\s_-]+');
+      const pattern = new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, 'i');
+      if (pattern.test(lower)) add(alias, 'known_alias', 'medium');
+      if (refs.length >= (options.maxFuzzyRefs ?? 5)) break;
+    }
+  }
+  return refs.slice(0, options.maxFuzzyRefs ?? 5);
+}

package/src/reference/resolve.mjs

@@ -0,0 +1,131 @@
+import { resolve } from 'node:path';
+import { usage } from '../cli/usage.mjs';
+import { readMemoryConfig } from '../memory/config.mjs';
+import { readFreshIndex } from '../index/cache.mjs';
+import { buildCompactImpactReport, buildImpactReport } from '../impact/report.mjs';
+import { DEFAULT_REFERENCE_LIMIT, extractBracketReferences, extractFuzzyReferences, isArchiveBodyPath, normalizeReferenceAlias, referenceCandidateAliases, referencePathForNode } from './extract.mjs';
+
+function incomingRouteBonus(graph, nodeId) {
+  return graph.edges.some((edge) => edge.target === nodeId && edge.relation === 'routes_to') ? 6 : 0;
+}
+
+function exactReferenceScore(ref, alias, kind) {
+  const rawRef = String(ref).trim().replace(/^\[\[/, '').replace(/\]\]$/, '').split('|')[0].trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  const rawAlias = String(alias).trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  if (rawRef === rawAlias) return kind === 'heading' ? 92 : 110;
+  if (rawRef.toLowerCase() === rawAlias.toLowerCase()) return kind === 'heading' ? 88 : 105;
+  return 0;
+}
+
+export function resolveReferenceCandidates(index, ref, options = {}) {
+  const graph = index?.graph ?? { nodes: [], edges: [] };
+  const includeArchive = options.includeArchive === true;
+  const limit = Number.isFinite(options.maxResults) ? options.maxResults : DEFAULT_REFERENCE_LIMIT;
+  const query = String(ref ?? '').trim().replace(/^\[\[/, '').replace(/\]\]$/, '').split('|')[0].trim();
+  const normalized = normalizeReferenceAlias(query);
+  const byId = new Map();
+  for (const node of graph.nodes ?? []) {
+    if (!['file', 'heading'].includes(node.type)) continue;
+    const path = referencePathForNode(node);
+    if (!includeArchive && isArchiveBodyPath(path)) continue;
+    let best = null;
+    for (const entry of referenceCandidateAliases(node)) {
+      const aliasKey = normalizeReferenceAlias(entry.alias);
+      if (!aliasKey) continue;
+      let score = exactReferenceScore(query, entry.alias, entry.kind);
+      if (aliasKey === normalized) score = Math.max(score, entry.kind === 'heading' ? 86 : 96);
+      else if (aliasKey.endsWith(normalized) && normalized.length >= 4) score = Math.max(score, entry.kind === 'heading' ? 62 : 70);
+      if (score <= 0) continue;
+      if (!best || score > best.score) best = { score, alias: entry.alias, aliasKind: entry.kind };
+    }
+    if (!best) continue;
+    const retrievalPriority = Number(node.retrievalPriority ?? node.retrieval?.priority ?? 30);
+    const routeBonus = incomingRouteBonus(graph, node.id);
+    const memoryBonus = Math.min(12, Math.max(0, retrievalPriority / 10));
+    const headingBonus = node.type === 'heading' ? 2 : 0;
+    const score = Number((best.score + routeBonus + memoryBonus + headingBonus).toFixed(1));
+    const reasons = [best.aliasKind === 'heading' ? 'heading_alias' : 'path_alias'];
+    if (routeBonus) reasons.push('readme_routed');
+    if (memoryBonus) reasons.push('memory_priority');
+    const candidate = { id: node.id, type: node.type, path, title: node.title, score, matchedAlias: best.alias, reasons, retrieval: node.retrieval, memoryArea: node.memoryArea };
+    const previous = byId.get(node.id);
+    if (!previous || candidate.score > previous.score) byId.set(node.id, candidate);
+  }
+  const candidates = [...byId.values()].sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.id.localeCompare(b.id));
+  const shown = candidates.slice(0, limit);
+  return { input: ref, query, normalized, candidates: shown, top: shown[0] ?? null, ambiguous: shown.length > 1 && shown[0].score - shown[1].score < 5, omitted: Math.max(0, candidates.length - shown.length) };
+}
+
+function parseReferenceOptions(argv, command) {
+  const filtered = [];
+  const options = { maxResults: DEFAULT_REFERENCE_LIMIT, includeArchive: false, withImpact: false, fuzzy: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--max-results') {
+      const next = argv[i + 1];
+      if (!next || next.startsWith('-') || Number.isNaN(Number.parseInt(next, 10))) usage('Missing or invalid value for --max-results.', command);
+      options.maxResults = Math.max(1, Number.parseInt(next, 10));
+      i += 1;
+    } else if (arg === '--include-archive') options.includeArchive = true;
+    else if (arg === '--with-impact') options.withImpact = true;
+    else if (arg === '--fuzzy') {
+      if (command !== 'expand') usage(`Unknown option: ${arg}`, command);
+      options.fuzzy = true;
+    }
+    else if (arg === '--json') filtered.push(arg);
+    else if (arg.startsWith('-')) usage(`Unknown option: ${arg}`, command);
+    else filtered.push(arg);
+  }
+  const operands = filtered.filter((arg) => !arg.startsWith('-'));
+  return { ...options, root: resolve(operands[0] ?? '.'), json: filtered.includes('--json'), rootArgv: operands.slice(1) };
+}
+
+function attachImpactToRef(index, refResult) {
+  const topPath = refResult.top?.path;
+  if (!topPath) return refResult;
+  const impact = buildCompactImpactReport(buildImpactReport(index, topPath));
+  return { ...refResult, impact: { changed: topPath, related: impact.related, groups: impact.groups, omittedRelated: impact.omittedRelated, quality: impact.quality } };
+}
+
+function formatReferenceOutput(payload) {
+  const refreshNote = payload.metadata.cacheRefreshed ? ', refreshed' : '';
+  const lines = [`${payload.command}: ${payload.refs.length} reference(s) (${payload.status.status}${refreshNote} index)`];
+  for (const ref of payload.refs) {
+    const marker = ref.ambiguous ? ' ambiguous' : '';
+    lines.push(`- ${ref.query || ref.input}:${marker} ${ref.candidates.length} candidate(s), ${ref.omitted} omitted`);
+    for (const candidate of ref.candidates) {
+      const title = candidate.title ? `#${candidate.title}` : '';
+      lines.push(`  - ${candidate.path}${title} (${candidate.score}; ${candidate.reasons.join(', ')})`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export function runResolve(argv) {
+  const options = parseReferenceOptions(argv, 'resolve');
+  const ref = options.rootArgv?.join(' ');
+  if (!ref) usage('Missing required argument: <ref>.', 'resolve');
+  const { status, index, metadata } = readFreshIndex(options.root);
+  const refs = [resolveReferenceCandidates(index, ref, options)];
+  const payload = { ok: status.ok, command: 'resolve', root: options.root, status, metadata, refs, omitted: refs.reduce((sum, item) => sum + item.omitted, 0) };
+  if (options.json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(formatReferenceOutput(payload));
+}
+
+export function runExpand(argv) {
+  const options = parseReferenceOptions(argv, 'expand');
+  const prompt = options.rootArgv?.join(' ');
+  if (!prompt) usage('Missing required argument: <prompt>.', 'expand');
+  const refsInPrompt = extractBracketReferences(prompt);
+  if (refsInPrompt.length === 0 && !options.fuzzy) usage('No [[refs]] found in prompt.', 'expand');
+  const { status, index, metadata } = readFreshIndex(options.root);
+  const fuzzyRefs = options.fuzzy ? extractFuzzyReferences(prompt, index, { ...options, memoryConfig: readMemoryConfig(options.root), existingTargets: refsInPrompt.map((item) => item.target) }) : [];
+  let refs = [
+    ...refsInPrompt.map((item) => ({ ...resolveReferenceCandidates(index, item.target, options), source: 'explicit', raw: item.raw, label: item.label })),
+    ...fuzzyRefs.map((item) => ({ ...resolveReferenceCandidates(index, item.target, options), source: 'fuzzy', raw: item.raw, confidence: item.confidence, reasons: item.reasons })),
+  ];
+  if (options.withImpact) refs = refs.map((item) => attachImpactToRef(index, item));
+  const payload = { ok: status.ok, command: 'expand', root: options.root, prompt, status, metadata, refs, omitted: refs.reduce((sum, item) => sum + item.omitted, 0) };
+  if (options.json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(formatReferenceOutput(payload));
+}

package/src/trello/client.mjs

@@ -0,0 +1,93 @@
+const TRELLO_API_BASE = 'https://api.trello.com';
+
+function clean(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function credentialError(message) {
+  return {
+    ok: false,
+    error: {
+      code: 'TRELLO_CREDENTIALS_MISSING',
+      message: `${message} Fix: configure GitHub Actions secrets or environment variables TRELLO_API_KEY and TRELLO_TOKEN, then retry from the trusted Trello sync workflow.`,
+    },
+  };
+}
+
+export function resolveTrelloCredentials({ env = process.env } = {}) {
+  const apiKey = clean(env.TRELLO_API_KEY);
+  const token = clean(env.TRELLO_TOKEN);
+  if (!apiKey || !token) return credentialError('Trello write mode credentials are missing or empty.');
+  return { ok: true, credentials: { apiKey, token, source: 'env' } };
+}
+
+function trelloApiError({ status = 0, statusText = '', body = '', retryAfter = null, operation = 'Trello API request', idOrShortLink = '', redact = (value) => value } = {}) {
+  const bodyText = redact(typeof body === 'string' ? body : JSON.stringify(body ?? ''));
+  const code = bodyText.includes('API_TOKEN_LIMIT_EXCEEDED') ? 'API_TOKEN_LIMIT_EXCEEDED' : bodyText.includes('API_KEY_LIMIT_EXCEEDED') ? 'API_KEY_LIMIT_EXCEEDED' : 'TRELLO_API_FAILED';
+  const rateLimitGuidance = status === 429 ? ` Wait and retry${retryAfter ? ` after ${retryAfter} seconds` : ''}.` : '';
+  return {
+    code,
+    status,
+    retryAfter,
+    message: `${operation} failed${idOrShortLink ? ` for Trello card ${idOrShortLink}` : ''}${status ? ` with HTTP ${status}${statusText ? ` ${statusText}` : ''}` : ''}${bodyText ? `: ${bodyText}` : ''}. Fix:${rateLimitGuidance || ' check card access, credentials, and Trello response details, then retry.'}`,
+  };
+}
+
+export function createTrelloClient({ credentials, fetchImpl = globalThis.fetch, baseUrl = TRELLO_API_BASE } = {}) {
+  if (typeof fetchImpl !== 'function') throw new Error('Trello client requires a fetch implementation.');
+  const auth = { key: credentials?.apiKey ?? '', token: credentials?.token ?? '' };
+  const redact = (value = '') => String(value).split(auth.key).join('[REDACTED_API_KEY]').split(auth.token).join('[REDACTED_TOKEN]');
+
+  async function request(path, { method = 'GET', params = {}, body = null, operation, idOrShortLink } = {}) {
+    const url = new URL(path, baseUrl);
+    for (const [key, value] of Object.entries({ ...params, ...auth })) url.searchParams.set(key, value);
+    const init = { method };
+    if (body !== null) {
+      init.headers = { 'Content-Type': 'application/json' };
+      init.body = JSON.stringify(body);
+    }
+    let response;
+    try {
+      response = await fetchImpl(url, init);
+    } catch (error) {
+      throw trelloApiError({ operation, idOrShortLink, body: error?.message ?? 'network error', redact });
+    }
+    const bodyText = await response.text();
+    if (!response.ok) {
+      throw trelloApiError({ status: response.status, statusText: response.statusText, body: bodyText, retryAfter: response.headers?.get?.('Retry-After') ?? null, operation, idOrShortLink, redact });
+    }
+    if (!bodyText) return null;
+    try {
+      return JSON.parse(bodyText);
+    } catch {
+      throw trelloApiError({ status: response.status, statusText: response.statusText, body: 'Malformed JSON response', operation, idOrShortLink, redact });
+    }
+  }
+
+  return {
+    async getCard(idOrShortLink) {
+      const card = await request(`/1/cards/${encodeURIComponent(idOrShortLink)}`, { params: { fields: 'id,idBoard,desc', customFieldItems: 'true' }, operation: 'Card lookup', idOrShortLink });
+      if (!card || typeof card.id !== 'string' || typeof card.idBoard !== 'string') throw trelloApiError({ body: 'Malformed card response', operation: 'Card lookup', idOrShortLink, redact });
+      return card;
+    },
+    async listAttachments(idOrShortLink) {
+      const attachments = await request(`/1/cards/${encodeURIComponent(idOrShortLink)}/attachments`, { operation: 'Attachment lookup', idOrShortLink });
+      if (!Array.isArray(attachments)) throw trelloApiError({ body: 'Malformed attachments response', operation: 'Attachment lookup', idOrShortLink, redact });
+      return attachments;
+    },
+    async createAttachment(idOrShortLink, githubUrl) {
+      return request(`/1/cards/${encodeURIComponent(idOrShortLink)}/attachments`, { method: 'POST', params: { url: githubUrl }, operation: 'Attachment creation', idOrShortLink });
+    },
+    async listCustomFields(idBoard) {
+      const fields = await request(`/1/boards/${encodeURIComponent(idBoard)}/customFields`, { operation: 'Custom field lookup' });
+      if (!Array.isArray(fields)) throw trelloApiError({ body: 'Malformed custom fields response', operation: 'Custom field lookup', redact });
+      return fields;
+    },
+    async createCustomField(idBoard, { name, type = 'text' } = {}) {
+      return request('/1/customFields', { method: 'POST', params: { idModel: idBoard, modelType: 'board', name, type, pos: 'bottom', display_cardFront: 'false' }, operation: 'Custom field creation' });
+    },
+    async updateCardCustomFieldText(idCard, idCustomField, text) {
+      return request(`/1/cards/${encodeURIComponent(idCard)}/customField/${encodeURIComponent(idCustomField)}/item`, { method: 'PUT', body: { value: { text } }, operation: 'Custom field update', idOrShortLink: idCard });
+    },
+  };
+}