@dotdotgod/cli 0.2.14 → 0.2.17

package/src/memory/config.mjs

@@ -6,9 +6,16 @@ import { isKebabCase } from '../docs/markdown.mjs';
 const MEMORY_CONFIG_FILE = 'dotdotgod.config.json';
 const MEMORY_SCOPES = new Set(['shared', 'local']);
 const MEMORY_FRESHNESS = new Set(['fresh', 'stale']);
+export const DEFAULT_TRACEABILITY_KEYS = [
+  { key: 'implementedBy', label: 'Implemented by', description: 'Files that implement the behavior.', target: 'path', relation: 'implemented_by', weight: 4 },
+  { key: 'verifiedBy', label: 'Verified by', description: 'Tests or maintained verification documents.', target: 'path', relation: 'verified_by', weight: 4 },
+  { key: 'relatedDocs', label: 'Related docs', description: 'Documents needed to interpret the behavior.', target: 'path', relation: 'related_doc', weight: 3 },
+  { key: 'verificationCommands', label: 'Verification commands', description: 'Project-local verification commands.', target: 'command', relation: 'verification_command', weight: 3 },
+];
 export const DEFAULT_TRACEABILITY_POLICY = {
   required: ['docs/spec/**'],
   exclude: ['**/README.md'],
+  keys: DEFAULT_TRACEABILITY_KEYS,
 };
 export const DEFAULT_VALIDATION_POLICY = {
   markdown: {
@@ -21,9 +28,6 @@ export const DEFAULT_VALIDATION_POLICY = {
     },
   },
 };
-export const DEFAULT_INTEGRATIONS_POLICY = {
-  trello: { syncPaths: [] },
-};
 export const DEFAULT_LOAD_POLICY = {
   pinnedPaths: [],
   pinnedBodies: [],
@@ -35,37 +39,27 @@ export const DEFAULT_PLAN_MODE_POLICY = {
   writablePaths: ['docs/plan/**', 'docs/archive/**'],
 };
 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 },
-  ppr: { enabled: true, damping: 0.85, iterations: 20, tolerance: 0.000001 },
+  connectionCap: 80,
+  memoryCap: 20,
+  ppr: { damping: 0.85, iterations: 20, tolerance: 0.000001, reference: 0.4 },
   relationWeights: {
-    implemented_by: 4,
-    verified_by: 4,
-    related_doc: 3,
-    verification_command: 3,
     links_to: 2,
+    routes_to: 2,
     belongs_to_area: 2,
-    semantic_similarity: 2,
-    mentions_package: 1,
+    vector_similarity: 2,
+    includes_resource: 1,
+    defines_contract: 2,
   },
-  traceabilityBoosts: { implemented_by: 30, 'incoming:implemented_by': 30, verified_by: 25, 'incoming:verified_by': 25, verification_command: 15, 'incoming:verification_command': 15, related_doc: 12, 'incoming:related_doc': 12 },
-  verificationBoosts: { verified_by: 15, 'incoming:verified_by': 15, verification_command: 12, 'incoming:verification_command': 12 },
-  semanticBoosts: { semantic_similarity: 8, 'incoming:semantic_similarity': 8, mentions_package: 4, 'incoming:mentions_package': 4 },
-  proximityBoosts: { links_to: 6, 'incoming:links_to': 6, routes_to: 5, 'incoming:routes_to': 5 },
-  semantic: { enabled: true, threshold: 0.5, topKPerFile: 5, includeArchiveBodies: false, signals: ['path', 'filename', 'heading', 'package'] },
-};
-const IMPACT_RANKING_PRESETS = {
-  balanced: {},
-  'docs-first': { weights: { ppr: 35, traceability: 35, memoryPolicy: 15, verification: 15, proximity: 5, semantic: 8, freshness: 5, archivePenalty: -30 } },
-  'code-proximity': { weights: { ppr: 45, traceability: 20, memoryPolicy: 8, verification: 12, proximity: 20, semantic: 8, freshness: 3, archivePenalty: -25 } },
-  'test-focused': { weights: { ppr: 35, traceability: 25, memoryPolicy: 8, verification: 25, proximity: 10, semantic: 7, freshness: 5, archivePenalty: -25 } },
-  'archive-aware': { weights: { ppr: 35, traceability: 25, memoryPolicy: 10, verification: 15, proximity: 10, semantic: 8, freshness: 3, archivePenalty: -10 } },
+  semantic: { enabled: true, threshold: 0.5, topKPerFile: 5 },
 };
-export const SEMANTIC_RELATIONS = new Set(['semantic_similarity', 'mentions_package']);
-const IMPACT_RANKING_WEIGHT_KEYS = new Set(['ppr', 'traceability', 'memoryPolicy', 'verification', 'proximity', 'semantic', 'freshness', 'archivePenalty']);
-const IMPACT_RANKING_RELATION_KEYS = new Set(['implemented_by', 'verified_by', 'related_doc', 'verification_command', 'links_to', 'belongs_to_area', 'semantic_similarity', 'mentions_package']);
-const IMPACT_RANKING_REASON_KEYS = new Set(['implemented_by', 'incoming:implemented_by', 'verified_by', 'incoming:verified_by', 'verification_command', 'incoming:verification_command', 'related_doc', 'incoming:related_doc', 'semantic_similarity', 'incoming:semantic_similarity', 'mentions_package', 'incoming:mentions_package', 'links_to', 'incoming:links_to', 'routes_to', 'incoming:routes_to']);
-const SEMANTIC_SIGNAL_KEYS = new Set(['path', 'filename', 'heading', 'package']);
+export const SEMANTIC_RELATIONS = new Set(['vector_similarity']);
+const TRACEABILITY_TARGETS = new Set(['path', 'command']);
+const TRACEABILITY_RESERVED_KEYS = new Set(['kind', 'contracts', 'id', 'title', 'sections']);
+export const BUILT_IN_GRAPH_RELATIONS = new Set([
+  'belongs_to_area', 'includes_resource', 'defines_contract', 'contains_heading', 'links_to', 'routes_to',
+  'declares_package', 'declares_script', 'declares_bin', 'depends_on', 'vector_similarity',
+]);
+const TRACEABILITY_RESERVED_RELATIONS = BUILT_IN_GRAPH_RELATIONS;
 const DEFAULT_FUZZY_LOW_SIGNAL_TERMS = [
   'a', 'an', 'and', 'are', 'as', 'by', 'docs', 'document', 'for', 'from', 'it', 'of', 'on', 'plan', 'test', 'the', 'to', 'update', 'version', 'with',
   '계획', '문서', '수정', '업데이트', '버전', '정보', '확인', '테스트',
@@ -112,13 +106,22 @@ function cloneArea(area) {
   }, area);
 }
 
+function cloneTraceabilityKey(definition) {
+  return { key: definition.key, label: definition.label, description: definition.description, target: definition.target, relation: definition.relation, weight: definition.weight };
+}
+
 export function cloneTraceabilityPolicy(policy = DEFAULT_TRACEABILITY_POLICY) {
   return {
     required: [...(policy.required ?? [])],
     exclude: [...(policy.exclude ?? [])],
+    keys: (policy.keys ?? DEFAULT_TRACEABILITY_KEYS).map(cloneTraceabilityKey),
   };
 }
 
+export function traceabilityRelationWeights(policy = DEFAULT_TRACEABILITY_POLICY) {
+  return Object.fromEntries((policy.keys ?? DEFAULT_TRACEABILITY_KEYS).map((definition) => [definition.relation, definition.weight]));
+}
+
 export function cloneValidationPolicy(policy = DEFAULT_VALIDATION_POLICY) {
   const filename = policy.markdown?.filename;
   return {
@@ -135,15 +138,11 @@ export function cloneValidationPolicy(policy = DEFAULT_VALIDATION_POLICY) {
 
 export function cloneImpactRankingPolicy(policy = DEFAULT_IMPACT_RANKING_POLICY) {
   return {
-    preset: policy.preset ?? 'balanced',
-    weights: { ...DEFAULT_IMPACT_RANKING_POLICY.weights, ...(policy.weights ?? {}) },
-    ppr: { ...DEFAULT_IMPACT_RANKING_POLICY.ppr, ...(policy.ppr ?? {}) },
-    relationWeights: { ...DEFAULT_IMPACT_RANKING_POLICY.relationWeights, ...(policy.relationWeights ?? {}) },
-    traceabilityBoosts: { ...DEFAULT_IMPACT_RANKING_POLICY.traceabilityBoosts, ...(policy.traceabilityBoosts ?? {}) },
-    verificationBoosts: { ...DEFAULT_IMPACT_RANKING_POLICY.verificationBoosts, ...(policy.verificationBoosts ?? {}) },
-    semanticBoosts: { ...DEFAULT_IMPACT_RANKING_POLICY.semanticBoosts, ...(policy.semanticBoosts ?? {}) },
-    proximityBoosts: { ...DEFAULT_IMPACT_RANKING_POLICY.proximityBoosts, ...(policy.proximityBoosts ?? {}) },
-    semantic: { ...DEFAULT_IMPACT_RANKING_POLICY.semantic, ...(policy.semantic ?? {}), signals: [...(policy.semantic?.signals ?? DEFAULT_IMPACT_RANKING_POLICY.semantic.signals)] },
+    connectionCap: DEFAULT_IMPACT_RANKING_POLICY.connectionCap,
+    memoryCap: DEFAULT_IMPACT_RANKING_POLICY.memoryCap,
+    ppr: { ...DEFAULT_IMPACT_RANKING_POLICY.ppr },
+    relationWeights: { ...DEFAULT_IMPACT_RANKING_POLICY.relationWeights },
+    semantic: { ...DEFAULT_IMPACT_RANKING_POLICY.semantic, ...(policy.semantic ?? {}) },
   };
 }
 
@@ -172,13 +171,16 @@ function normalizeReferenceExpansionPolicy(raw) {
 }
 
 function normalizeImpactRankingPolicy(raw) {
-  const presetName = typeof raw?.preset === 'string' ? raw.preset : 'balanced';
-  const preset = IMPACT_RANKING_PRESETS[presetName] ?? IMPACT_RANKING_PRESETS.balanced;
-  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 ?? [])] } };
+  const candidate = raw && typeof raw === 'object' && !Array.isArray(raw)
+    && raw.semantic && typeof raw.semantic === 'object' && !Array.isArray(raw.semantic)
+    ? raw.semantic
+    : {};
+  const semantic = {
+    ...(typeof candidate.enabled === 'boolean' ? { enabled: candidate.enabled } : {}),
+    ...(isFiniteNumberInRange(candidate.threshold, 0, 1) ? { threshold: candidate.threshold } : {}),
+    ...(Number.isInteger(candidate.topKPerFile) && candidate.topKPerFile >= 0 && candidate.topKPerFile <= 20 ? { topKPerFile: candidate.topKPerFile } : {}),
+  };
+  return cloneImpactRankingPolicy({ semantic });
 }
 
 export function cloneLoadPolicy(policy = DEFAULT_LOAD_POLICY) {
@@ -196,7 +198,7 @@ export function clonePlanModePolicy(policy = DEFAULT_PLAN_MODE_POLICY) {
 }
 
 export function defaultMemoryConfig() {
-  return { source: 'default', areas: DEFAULT_MEMORY_AREAS.map(cloneArea), traceability: cloneTraceabilityPolicy(), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy(), integrations: cloneIntegrationsPolicy(), load: cloneLoadPolicy(), planMode: clonePlanModePolicy() };
+  return { source: 'default', areas: DEFAULT_MEMORY_AREAS.map(cloneArea), traceability: cloneTraceabilityPolicy(), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy(), load: cloneLoadPolicy(), planMode: clonePlanModePolicy() };
 }
 
 export function normalizePathPattern(value = '') {
@@ -244,6 +246,7 @@ function normalizeTraceabilityPolicy(raw) {
   return {
     required: Array.isArray(raw.required) ? raw.required.map(normalizePathPattern) : [],
     exclude: Array.isArray(raw.exclude) ? raw.exclude.map(normalizePathPattern) : [],
+    keys: (raw.keys === undefined ? DEFAULT_TRACEABILITY_KEYS : raw.keys).map(cloneTraceabilityKey),
   };
 }
 
@@ -264,12 +267,6 @@ 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)] } });
-}
-
 export function isSecretLikePathPattern(value = '') {
   const normalized = normalizePathPattern(value);
   return /(^|\/)(\.env|\.npmrc|\.pypirc|id_rsa|id_dsa|id_ed25519|credentials?|secrets?)(\.|\/|$)/i.test(normalized);
@@ -287,8 +284,8 @@ function normalizeLoadPolicy(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return cloneLoadPolicy();
   const normalize = (values) => (Array.isArray(values) ? [...new Set(values.map(normalizePathPattern))] : []);
   return cloneLoadPolicy({
-    pinnedPaths: normalize(raw.pinnedPaths),
-    pinnedBodies: normalize(raw.pinnedBodies),
+    pinnedPaths: [],
+    pinnedBodies: [],
     documentationSummary: {
       exclude: raw.documentationSummary?.exclude === undefined
         ? DEFAULT_LOAD_POLICY.documentationSummary.exclude
@@ -297,10 +294,6 @@ function normalizeLoadPolicy(raw) {
   });
 }
 
-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) => matchPathPattern(path, pattern));
@@ -331,10 +324,6 @@ function isFiniteNumberInRange(value, min, max) {
   return typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max;
 }
 
-function validateNumberMap(map, keys, min, max) {
-  return map && typeof map === 'object' && !Array.isArray(map) && Object.entries(map).every(([key, value]) => keys.has(key) && isFiniteNumberInRange(value, min, max));
-}
-
 export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.config.json') {
   const errors = [];
   const add = (code, field, message, fix = null) => errors.push({
@@ -355,6 +344,26 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
       else if (traceability.required.some((value) => !isValidPathPattern(value))) add('TRACEABILITY_CONFIG_INVALID_REQUIRED', 'traceability.required', 'Expected path strings using exact paths, /** subtree patterns, or **/suffix patterns.');
       if (traceability.exclude !== undefined && !Array.isArray(traceability.exclude)) add('TRACEABILITY_CONFIG_INVALID_EXCLUDE', 'traceability.exclude', 'Expected an array of path strings.');
       else if (Array.isArray(traceability.exclude) && traceability.exclude.some((value) => !isValidPathPattern(value))) add('TRACEABILITY_CONFIG_INVALID_EXCLUDE', 'traceability.exclude', 'Expected path strings using exact paths, /** subtree patterns, or **/suffix patterns.');
+      if (traceability.keys !== undefined && !Array.isArray(traceability.keys)) add('TRACEABILITY_CONFIG_INVALID_KEYS', 'traceability.keys', 'Expected an array of traceability key definitions.');
+      else if (Array.isArray(traceability.keys)) {
+        const keys = new Set();
+        const labels = new Set();
+        const relations = new Set();
+        for (const [index, definition] of traceability.keys.entries()) {
+          const prefix = `traceability.keys[${index}]`;
+          if (!definition || typeof definition !== 'object' || Array.isArray(definition)) { add('TRACEABILITY_CONFIG_INVALID_KEY', prefix, 'Expected an object.'); continue; }
+          const allowed = new Set(['key', 'label', 'description', 'target', 'relation', 'weight']);
+          if (Object.keys(definition).some((key) => !allowed.has(key))) add('TRACEABILITY_CONFIG_INVALID_KEY', prefix, 'Contains unsupported fields.');
+          if (typeof definition.key !== 'string' || !/^[A-Za-z][A-Za-z0-9]*$/.test(definition.key) || TRACEABILITY_RESERVED_KEYS.has(definition.key) || keys.has(definition.key)) add('TRACEABILITY_CONFIG_INVALID_KEY', `${prefix}.key`, 'Expected a unique non-reserved identifier.'); else keys.add(definition.key);
+          const trimmedLabel = typeof definition.label === 'string' ? definition.label.trim() : '';
+          const normalizedLabel = trimmedLabel.toLocaleLowerCase();
+          if (!normalizedLabel || /[\u0000-\u001f\u007f]/.test(trimmedLabel) || labels.has(normalizedLabel)) add('TRACEABILITY_CONFIG_INVALID_LABEL', `${prefix}.label`, 'Expected a unique single-line non-empty label after trimming and case normalization.'); else labels.add(normalizedLabel);
+          if (typeof definition.description !== 'string' || !definition.description.trim()) add('TRACEABILITY_CONFIG_INVALID_DESCRIPTION', `${prefix}.description`, 'Expected a non-empty description.');
+          if (!TRACEABILITY_TARGETS.has(definition.target)) add('TRACEABILITY_CONFIG_INVALID_TARGET', `${prefix}.target`, 'Expected "path" or "command".');
+          if (typeof definition.relation !== 'string' || !/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/.test(definition.relation) || TRACEABILITY_RESERVED_RELATIONS.has(definition.relation) || relations.has(definition.relation)) add('TRACEABILITY_CONFIG_INVALID_RELATION', `${prefix}.relation`, 'Expected a unique canonical snake_case relation not reserved by the graph.'); else relations.add(definition.relation);
+          if (!isFiniteNumberInRange(definition.weight, 0, 20)) add('TRACEABILITY_CONFIG_INVALID_WEIGHT', `${prefix}.weight`, 'Expected a finite number from 0 to 20.');
+        }
+      }
     }
   }
   const validation = data.validation;
@@ -383,37 +392,11 @@ 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 load = data.load;
   if (load !== undefined) {
     if (!load || typeof load !== 'object' || Array.isArray(load)) {
       add('LOAD_CONFIG_INVALID', 'load', 'Expected an object.');
     } else {
-      for (const [key, code] of [['pinnedPaths', 'LOAD_CONFIG_INVALID_PINNED_PATHS'], ['pinnedBodies', 'LOAD_CONFIG_INVALID_PINNED_BODIES']]) {
-        const values = load[key];
-        if (values === undefined) continue;
-        if (!Array.isArray(values)) add(code, `load.${key}`, 'Expected an array of path strings.');
-        else {
-          if (values.some((value) => !isValidPathPattern(value) || (typeof value === 'string' && value.trim().startsWith('/')))) add(code, `load.${key}`, 'Expected repository-relative path strings using exact paths, /** subtree patterns, or **/suffix patterns.');
-          if (values.some((value) => typeof value === 'string' && isSecretLikePathPattern(value))) add('LOAD_CONFIG_SECRET_PINNED_PATH', `load.${key}`, 'Pinned load paths must not target secrets, credentials, environment files, or private keys.');
-        }
-      }
       if (load.documentationSummary !== undefined) {
         const summary = load.documentationSummary;
         if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
@@ -455,40 +438,6 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
       }
     }
   }
-  const impactRanking = data.impactRanking;
-  if (impactRanking !== undefined) {
-    if (!impactRanking || typeof impactRanking !== 'object' || Array.isArray(impactRanking)) {
-      add('IMPACT_RANKING_CONFIG_INVALID', 'impactRanking', 'Expected an object.');
-    } else {
-      if (impactRanking.preset !== undefined && !Object.hasOwn(IMPACT_RANKING_PRESETS, impactRanking.preset)) add('IMPACT_RANKING_CONFIG_INVALID_PRESET', 'impactRanking.preset', 'Expected one of balanced, docs-first, code-proximity, test-focused, or archive-aware.');
-      if (impactRanking.weights !== undefined && !validateNumberMap(impactRanking.weights, IMPACT_RANKING_WEIGHT_KEYS, -100, 100)) add('IMPACT_RANKING_CONFIG_INVALID_WEIGHTS', 'impactRanking.weights', 'Expected known numeric weight keys with finite values from -100 to 100.');
-      if (impactRanking.relationWeights !== undefined && !validateNumberMap(impactRanking.relationWeights, IMPACT_RANKING_RELATION_KEYS, 0, 20)) add('IMPACT_RANKING_CONFIG_INVALID_RELATION_WEIGHTS', 'impactRanking.relationWeights', 'Expected known relation keys with finite values from 0 to 20.');
-      for (const key of ['traceabilityBoosts', 'verificationBoosts', 'semanticBoosts', 'proximityBoosts']) {
-        if (impactRanking[key] !== undefined && !validateNumberMap(impactRanking[key], IMPACT_RANKING_REASON_KEYS, 0, 100)) add('IMPACT_RANKING_CONFIG_INVALID_BOOSTS', `impactRanking.${key}`, 'Expected known reason keys with finite values from 0 to 100.');
-      }
-      if (impactRanking.ppr !== undefined) {
-        const ppr = impactRanking.ppr;
-        if (!ppr || typeof ppr !== 'object' || Array.isArray(ppr)) add('IMPACT_RANKING_CONFIG_INVALID_PPR', 'impactRanking.ppr', 'Expected an object.');
-        else {
-          if (ppr.enabled !== undefined && typeof ppr.enabled !== 'boolean') add('IMPACT_RANKING_CONFIG_INVALID_PPR', 'impactRanking.ppr.enabled', 'Expected a boolean.');
-          if (ppr.damping !== undefined && !isFiniteNumberInRange(ppr.damping, 0.01, 0.99)) add('IMPACT_RANKING_CONFIG_INVALID_PPR', 'impactRanking.ppr.damping', 'Expected a number greater than 0 and less than 1.');
-          if (ppr.iterations !== undefined && (!Number.isInteger(ppr.iterations) || ppr.iterations < 1 || ppr.iterations > 100)) add('IMPACT_RANKING_CONFIG_INVALID_PPR', 'impactRanking.ppr.iterations', 'Expected an integer from 1 to 100.');
-          if (ppr.tolerance !== undefined && !isFiniteNumberInRange(ppr.tolerance, 0, 1)) add('IMPACT_RANKING_CONFIG_INVALID_PPR', 'impactRanking.ppr.tolerance', 'Expected a number from 0 to 1.');
-        }
-      }
-      if (impactRanking.semantic !== undefined) {
-        const semantic = impactRanking.semantic;
-        if (!semantic || typeof semantic !== 'object' || Array.isArray(semantic)) add('IMPACT_RANKING_CONFIG_INVALID_SEMANTIC', 'impactRanking.semantic', 'Expected an object.');
-        else {
-          if (semantic.enabled !== undefined && typeof semantic.enabled !== 'boolean') add('IMPACT_RANKING_CONFIG_INVALID_SEMANTIC', 'impactRanking.semantic.enabled', 'Expected a boolean.');
-          if (semantic.threshold !== undefined && !isFiniteNumberInRange(semantic.threshold, 0, 1)) add('IMPACT_RANKING_CONFIG_INVALID_SEMANTIC', 'impactRanking.semantic.threshold', 'Expected a number from 0 to 1.');
-          if (semantic.topKPerFile !== undefined && (!Number.isInteger(semantic.topKPerFile) || semantic.topKPerFile < 0 || semantic.topKPerFile > 20)) add('IMPACT_RANKING_CONFIG_INVALID_SEMANTIC', 'impactRanking.semantic.topKPerFile', 'Expected an integer from 0 to 20.');
-          if (semantic.includeArchiveBodies !== undefined && typeof semantic.includeArchiveBodies !== 'boolean') add('IMPACT_RANKING_CONFIG_INVALID_SEMANTIC', 'impactRanking.semantic.includeArchiveBodies', 'Expected a boolean.');
-          if (semantic.signals !== undefined && (!Array.isArray(semantic.signals) || semantic.signals.some((value) => !SEMANTIC_SIGNAL_KEYS.has(value)))) add('IMPACT_RANKING_CONFIG_INVALID_SEMANTIC', 'impactRanking.semantic.signals', 'Expected an array of known deterministic signal names.');
-        }
-      }
-    }
-  }
   const areas = data.memory?.areas;
   if (areas === undefined) return errors;
   if (!Array.isArray(areas)) {
@@ -544,10 +493,9 @@ export function readMemoryConfig(root = '.') {
     const validation = data.validation === undefined ? cloneValidationPolicy() : normalizeValidationPolicy(data.validation);
     const impactRanking = normalizeImpactRankingPolicy(data.impactRanking);
     const referenceExpansion = normalizeReferenceExpansionPolicy(data.referenceExpansion);
-    const integrations = normalizeIntegrationsPolicy(data.integrations);
     const load = normalizeLoadPolicy(data.load);
     const planMode = normalizePlanModePolicy(data.planMode);
-    return configuredAreas.length > 0 ? { source: MEMORY_CONFIG_FILE, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, source: MEMORY_CONFIG_FILE, errors: [] };
+    return configuredAreas.length > 0 ? { source: MEMORY_CONFIG_FILE, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, load, planMode, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, load, planMode, source: MEMORY_CONFIG_FILE, errors: [] };
   } catch (error) {
     return { ...defaultMemoryConfig(), source: MEMORY_CONFIG_FILE, errors: [{ file: MEMORY_CONFIG_FILE, code: 'MEMORY_CONFIG_INVALID_JSON', message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}\nFix: repair ${MEMORY_CONFIG_FILE} so it is valid JSON, or remove it before regenerating the default config with \`dotdotgod config init <root>\`.` }] };
   }
@@ -575,9 +523,8 @@ export function defaultDotdotgodConfigData() {
     },
     traceability: cloneTraceabilityPolicy(config.traceability),
     validation: cloneValidationPolicy(config.validation),
-    impactRanking: cloneImpactRankingPolicy(config.impactRanking),
+    impactRanking: { semantic: { ...config.impactRanking.semantic } },
     referenceExpansion: { fuzzy: { lowSignal: { add: [], remove: [] } } },
-    integrations: cloneIntegrationsPolicy(config.integrations),
     load: cloneLoadPolicy(config.load),
     planMode: clonePlanModePolicy(config.planMode),
   };
@@ -603,9 +550,16 @@ export function memoryConfigSummary(config) {
     }, area)),
     traceability: cloneTraceabilityPolicy(config.traceability ?? DEFAULT_TRACEABILITY_POLICY),
     validation: cloneValidationPolicy(config.validation ?? DEFAULT_VALIDATION_POLICY),
-    impactRanking: cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY),
+    impactRanking: {
+      fixed: {
+        connectionCap: DEFAULT_IMPACT_RANKING_POLICY.connectionCap,
+        memoryCap: DEFAULT_IMPACT_RANKING_POLICY.memoryCap,
+        ppr: { ...DEFAULT_IMPACT_RANKING_POLICY.ppr },
+        relationWeights: { ...DEFAULT_IMPACT_RANKING_POLICY.relationWeights },
+      },
+      semantic: { ...cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY).semantic },
+    },
     referenceExpansion: cloneReferenceExpansionPolicy(config.referenceExpansion),
-    integrations: cloneIntegrationsPolicy(config.integrations),
     load: cloneLoadPolicy(config.load),
     planMode: clonePlanModePolicy(config.planMode),
   };

package/src/memory/summary.mjs

@@ -1,8 +1,6 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { rel } from '../common/paths.mjs';
-import { isExcludedIndexDir } from '../index/files.mjs';
-import { defaultMemoryConfig, isSecretLikePathPattern, matchPathPattern, memoryAreaForPath } from './config.mjs';
+import { defaultMemoryConfig, memoryAreaForPath } from './config.mjs';
 
 export function detectPackageManager(root) {
   const packageFile = join(root, 'package.json');
@@ -50,98 +48,6 @@ export function detectCommandGuidance(root) {
   };
 }
 
-const PINNED_WALK_CAP = 200;
-
-function walkPinnedMatches(root, base, matches, cap) {
-  if (!existsSync(base)) return [];
-  const results = [];
-  const walk = (dir) => {
-    if (results.length >= cap) return;
-    let entries;
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    entries.sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      if (results.length >= cap) return;
-      const absolute = join(dir, entry.name);
-      const path = rel(root, absolute);
-      if (entry.isDirectory()) {
-        if (!isExcludedIndexDir(path)) walk(absolute);
-      } else if (entry.isFile() && matches(path)) results.push(path);
-    }
-  };
-  walk(base);
-  return results;
-}
-
-function expandPinnedPattern(root, pattern) {
-  if (!pattern.includes('*')) {
-    try {
-      return statSync(join(root, pattern)).isFile() ? [pattern] : [];
-    } catch {
-      return [];
-    }
-  }
-  const base = pattern.endsWith('/**') ? join(root, pattern.slice(0, -3)) : root;
-  return walkPinnedMatches(root, base, (path) => !isSecretLikePathPattern(path) && matchPathPattern(path, pattern), PINNED_WALK_CAP);
-}
-
-function readPinnedBody(root, path, maxBodyChars) {
-  if (isSecretLikePathPattern(path)) return { path, status: 'skipped', reason: 'secret-like-path' };
-  let content;
-  try {
-    content = readFileSync(join(root, path));
-  } catch {
-    return { path, status: 'missing' };
-  }
-  if (content.includes(0)) return { path, status: 'skipped', reason: 'binary' };
-  const text = content.toString('utf8');
-  const truncated = text.length > maxBodyChars;
-  return { path, status: truncated ? 'truncated' : 'present', truncated, chars: text.length, content: truncated ? text.slice(0, maxBodyChars) : text };
-}
-
-export function buildPinnedFiles(root, config = defaultMemoryConfig(), limits = {}) {
-  const policy = config.load ?? { pinnedPaths: [], pinnedBodies: [] };
-  const maxPaths = limits.paths ?? 20;
-  const maxBodies = limits.bodies ?? 5;
-  const maxBodyChars = limits.bodyChars ?? 10000;
-  const entries = new Map();
-  const addMatches = (pattern, kind) => {
-    const matches = expandPinnedPattern(root, pattern);
-    for (const path of matches.length > 0 ? matches : [pattern]) {
-      const entry = entries.get(path) ?? { path, status: matches.length > 0 ? 'present' : 'missing', pinnedBy: new Set() };
-      entry.pinnedBy.add(kind);
-      entries.set(path, entry);
-    }
-    return matches;
-  };
-  for (const pattern of policy.pinnedPaths ?? []) addMatches(pattern, 'pinnedPaths');
-  const bodyCandidates = new Set();
-  for (const pattern of policy.pinnedBodies ?? []) {
-    for (const path of addMatches(pattern, 'pinnedBodies')) bodyCandidates.add(path);
-  }
-  const allPaths = [...entries.values()].sort((a, b) => a.path.localeCompare(b.path));
-  const paths = allPaths.slice(0, maxPaths).map((entry) => ({ path: entry.path, status: entry.status, pinnedBy: [...entry.pinnedBy].sort() }));
-  const bodies = [];
-  let omittedBodies = 0;
-  for (const path of [...bodyCandidates].sort()) {
-    if (bodies.length >= maxBodies) omittedBodies += 1;
-    else bodies.push(readPinnedBody(root, path, maxBodyChars));
-  }
-  return {
-    source: config.source ?? 'default',
-    configured: { pinnedPaths: [...(policy.pinnedPaths ?? [])], pinnedBodies: [...(policy.pinnedBodies ?? [])] },
-    paths,
-    omittedPaths: allPaths.length - paths.length,
-    bodies,
-    omittedBodies,
-    bounds: { maxPaths, maxBodies, maxBodyChars },
-  };
-}
-
 export function buildMemoryAreas(index, limits = {}) {
   const graph = index?.graph ?? { nodes: [], edges: [] };
   const itemLimit = limits.items ?? 4;

package/src/query/store.mjs

@@ -5,6 +5,20 @@ export const VECTOR_SCHEMA_VERSION = 1;
 export const VECTOR_MODEL = 'Xenova/multilingual-e5-small';
 export const VECTOR_DIMENSIONS = 384;
 
+export function isValidNormalizedVectorValues(values) {
+  if (!values || values.length % VECTOR_DIMENSIONS !== 0) return false;
+  for (let offset = 0; offset < values.length; offset += VECTOR_DIMENSIONS) {
+    let squaredNorm = 0;
+    for (let index = 0; index < VECTOR_DIMENSIONS; index += 1) {
+      const value = values[offset + index];
+      if (!Number.isFinite(value) || value < -1 || value > 1) return false;
+      squaredNorm += value * value;
+    }
+    if (Math.abs(Math.sqrt(squaredNorm) - 1) > 0.01) return false;
+  }
+  return true;
+}
+
 export function vectorCachePaths(root) {
   const directory = join(root, '.dotdotgod', 'vectors');
   return {
@@ -25,6 +39,7 @@ export function readVectorCache(root) {
     const buffer = readFileSync(paths.embeddings);
     if (buffer.byteLength !== chunks.length * VECTOR_DIMENSIONS * 4) return null;
     const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
+    if (!isValidNormalizedVectorValues(vectors)) return null;
     return { manifest, chunks, vectors: new Float32Array(vectors) };
   } catch {
     return null;
@@ -41,6 +56,7 @@ export function writeVectorCache(root, chunks, vectors, metadata = {}) {
   const paths = vectorCachePaths(root);
   mkdirSync(paths.directory, { recursive: true });
   if (vectors.length !== chunks.length * VECTOR_DIMENSIONS) throw new Error('Vector count does not match chunk metadata.');
+  if (!isValidNormalizedVectorValues(vectors)) throw new Error('Vectors must contain finite normalized values.');
   const manifest = {
     schemaVersion: VECTOR_SCHEMA_VERSION,
     model: VECTOR_MODEL,

package/src/validate/run.mjs

@@ -61,9 +61,17 @@ export function runValidate(argv) {
   const maxChars = options.maxChars ?? validationPolicy.markdown.maxChars;
   const markdownSizePrompt = (path) => {
     const area = resolveMemoryArea(path, memoryConfig);
-    const areaText = area ? `${area.label ?? area.id} (${area.id})` : 'the matching documentation area';
-    const roleText = area?.role ?? 'the document role';
-    return `Split ${path} into focused documents by documentation area and role. Keep the current ${areaText} area semantics and ${roleText} role intact, move role-specific detail into smaller UPPER_SNAKE_CASE markdown files, and update the nearest README.md index with each new file's purpose.`;
+    const clarify = area?.clarify;
+    const guidance = [
+      clarify?.documentType ? `document type: ${clarify.documentType}` : null,
+      clarify?.audience?.length ? `audience: ${clarify.audience.join(', ')}` : null,
+      clarify?.clarityGoal ? `clarity goal: ${clarify.clarityGoal}` : null,
+      clarify?.editRules?.length ? `edit rules: ${clarify.editRules.join('; ')}` : null,
+    ].filter(Boolean);
+    const evidence = guidance.length > 0
+      ? ` Follow this resolved clarification guidance: ${guidance.join('; ')}.`
+      : ' Preserve the document\'s current purpose and established meaning, using its content, links, and nearest README.md as evidence.';
+    return `Split ${path} into focused UPPER_SNAKE_CASE markdown files.${evidence} Keep each file focused and update the nearest README.md index with every new file's purpose.`;
   };
   for (const error of memoryConfig.errors ?? []) errors.push(error);
   const FILENAME_QUALITY_AREAS = new Set(
@@ -73,18 +81,14 @@ export function runValidate(argv) {
       .map(p => { const m = p.match(/^docs\/([^/*]+)\/\*\*$/); return m ? m[1] : null; })
       .filter(Boolean)
   );
+  const filenameQualityScope = [...FILENAME_QUALITY_AREAS].sort().map(area => `docs/${area}`).join(', ') || 'configured shared documentation areas';
   const FILENAME_QUALITY_PROMPT =
-    'Background: Filenames and paths are LLM/agent context signals used for impact ranking, search, and retrieval. ' +
-    'Abstract or sequentially numbered filenames carry low information signal.\n' +
-    'Naming principles:\n' +
-    '1. Filenames in docs/spec, docs/arch, docs/test should be meaning-based wherever possible.\n' +
-    '2. The filename alone should let you infer the primary subject: endpoint, screen, policy, state, or response type.\n' +
-    '3. When splitting documents, derive names from headings, API paths, or domain terms rather than sequence numbers or abstract words.\n' +
-    'Avoid - numbered splits: API_1.md, API_2.md, API_3_1_*.md, 01_*.md, *_01.md\n' +
-    'Avoid - overly abstract: COMMON.md, OVERVIEW.md, DETAILS.md, NOTES.md, MISC.md, PART_1.md, SECTION_1.md\n' +
-    'Acceptable exceptions: README.md (directory index), files with clear HTTP status code semantics (e.g. RESPONSE_200_OK.md), ' +
-    'files in the project validation.markdown.filename.allow allowlist.\n' +
-    'Good renames: API_1.md → BIZ_RESERVATIONS_SCHEDULE.md, COMMON.md → BIZ_AUTH_ERROR_CONVENTIONS.md, OVERVIEW.md → REGISTRATION_HANDOFF_SUMMARY.md';
+    'Filenames and paths are LLM/agent context signals used for impact ranking, search, and retrieval.\n' +
+    `Use meaning-based filenames in ${filenameQualityScope}. A filename should identify its primary endpoint, screen, policy, state, response type, or domain subject. ` +
+    'Derive split-document names from headings, API paths, and established domain terms.\n' +
+    'Rename numbered or abstract series such as API_1.md, PART_1.md, COMMON.md, or DETAILS.md to subject-specific names. ' +
+    'Examples: API_1.md → BIZ_RESERVATIONS_SCHEDULE.md; COMMON.md → BIZ_AUTH_ERROR_CONVENTIONS.md.\n' +
+    'README.md directory indexes, clear HTTP-status filenames such as RESPONSE_200_OK.md, and configured filename allowlist entries remain valid.';
   walk(docs);
   const dirSiblingMap = new Map();
   for (const f of markdownFiles) {
@@ -131,7 +135,7 @@ export function runValidate(argv) {
         if (block.error) addError(file, 'TRACEABILITY_INVALID_JSON', `Invalid \`json dotdotgod\` block: ${block.error}\nFix: repair the fenced \`json dotdotgod\` block so it is valid JSON and still matches the expected schema.\n\n${traceabilityExample()}`, block.line);
         else {
           for (const error of validateTraceabilityBlock(block.data, root, file, block.line, memoryConfig)) errors.push(error);
-          const synced = syncTraceabilityLinksInContent(content, block.data, root, file);
+          const synced = syncTraceabilityLinksInContent(content, block.data, root, file, memoryConfig);
           if (synced.ok && synced.changed) addError(file, 'TRACEABILITY_LINKS_STALE', 'Generated traceability links or compact traceability JSON are missing or stale.', block.line, 'run `dotdotgod traceability links <root> --write` to synchronize the generated Markdown links and compact JSON block.');
         }
       }