@dotdotgod/cli 0.2.15 → 0.2.18

package/README.md

@@ -38,7 +38,7 @@ dotdotgod graph impact . --changed <path> --compact
 - `index` builds `.dotdotgod/manifest.json` and compact graph shards from maintained project files.
 - `query` locally embeds shared Markdown with `Xenova/multilingual-e5-small`, incrementally stores vectors under `.dotdotgod/vectors/`, and returns the best-ranked chunk from each relevant Markdown file.
 - `resolve` and `expand` map explicit or high-signal prompt references to project files.
-- `graph impact` ranks likely related specs, tests, docs, commands, and source files for one or more changed paths, with a combined ranking and per-file top five.
+- `graph impact` ranks likely related specs, tests, docs, commands, and source files for one or more changed paths, with a combined ranking and per-file top five. Non-seed scores use fixed weighted PPR connection `80` plus memory policy `20`. A bounded request-local multilingual vector overlay participates in PPR when the query cache is available; vector preparation failures degrade to structural-only results.
 - `traceability links` checks or repairs generated Markdown traceability-link sections.
 
 ## Commands
@@ -85,17 +85,19 @@ $ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact
 
 ```text
 docs:
-- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
-- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
+- docs/spec/CONFIG_COMMAND.md (56.8; incoming:links_to, incoming:implemented_by)
+- docs/spec/cli/TRACEABILITY_LINKS.md (26.3; vector_similarity)
+
+tests:
+- packages/cli/test/core.test.mjs (6.5; verified_by)
 
 files:
 - packages/cli/src/core.mjs (100; changed-file)
-- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
 ```
 
 `graph impact` needs at least one `--changed <path>` and accepts repeated options. Multi-file output preserves input order, deduplicates repeated paths, returns a bounded combined ranking, and includes the top five non-seed results for each changed file. Use `--compact` for short text, `--yml` or `--yaml` for compact structured agent-facing output, and `--json` for machine-readable detail.
 
-The graph is built from maintained project files: Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, imports, exports, commands, tests, and deterministic routing hints.
+The indexed graph is built from maintained project files: Markdown links, README routes, headings, configured traceability relations, package metadata, scripts and packaged resources, dependencies, and memory-area membership. Impact analysis can add request-local vector edges for candidate discovery and PPR without mutating that indexed graph.
 
 ## Validation and Verification Boundaries
 
@@ -119,7 +121,7 @@ The default scaffold gives docs explicit roles:
 - `docs/archive/README.md`: local archive map included by default.
 - `docs/archive/**`: local archive bodies excluded by default unless targeted.
 
-Use `memory.areas` to customize memory classification and retrieval priority. Use `traceability.required` and `traceability.exclude` to customize which Markdown paths need `json dotdotgod` traceability blocks. Use `validation.markdown`, `impactRanking`, and `referenceExpansion` to tune size budgets, impact scoring, and fuzzy prompt matching.
+Use `memory.areas` to customize memory classification and retrieval priority. Use `traceability.required` and `traceability.exclude` to select which Markdown paths need `json dotdotgod` blocks, and use ordered `traceability.keys` definitions to configure string-array labels, path or command targets, graph relations, and PPR weights. Use `validation.markdown` for size budgets and `referenceExpansion` for fuzzy prompt matching. The complete `impactRanking` namespace is non-blocking compatibility input: valid semantic candidate controls apply, malformed values fall back to defaults, and retired or unknown fields are ignored without changing fixed scoring. Legacy `load.pinnedPaths` and `load.pinnedBodies` values are also ignored.
 
 ## Indexing Scope
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.2.15",
+  "version": "0.2.18",
   "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/commands/config.mjs

@@ -36,9 +36,12 @@ function formatConfigOutput(payload) {
   lines.push(`- memory areas: ${payload.config.areas.length}`);
   lines.push(`- traceability required: ${(payload.config.traceability.required ?? []).join(', ') || 'none'}`);
   lines.push(`- traceability exclude: ${(payload.config.traceability.exclude ?? []).join(', ') || 'none'}`);
+  lines.push('- traceability keys:');
+  for (const definition of payload.config.traceability.keys ?? []) lines.push(`  - ${definition.key}: ${definition.target} -> ${definition.relation} (weight=${definition.weight}; label=${definition.label})`);
   lines.push(`- validation markdown: maxLines=${payload.config.validation.markdown.maxLines}, maxChars=${payload.config.validation.markdown.maxChars}`);
   lines.push(`- validation markdown exclude: ${(payload.config.validation.markdown.exclude ?? []).join(', ') || 'none'}`);
-  lines.push(`- impact ranking preset: ${payload.config.impactRanking.preset}`);
+  const fixedImpact = payload.config.impactRanking.fixed;
+  lines.push(`- impact ranking: fixed PPR=${fixedImpact.connectionCap}, memory=${fixedImpact.memoryCap}, reference=${fixedImpact.ppr.reference}`);
   lines.push(`- load pinned paths: ${(payload.config.load?.pinnedPaths ?? []).join(', ') || 'none'}`);
   lines.push(`- load pinned bodies: ${(payload.config.load?.pinnedBodies ?? []).join(', ') || 'none'}`);
   lines.push(`- load documentation summary exclude: ${(payload.config.load?.documentationSummary?.exclude ?? []).join(', ') || 'none'}`);

package/src/commands/graph.mjs

@@ -2,6 +2,8 @@ import { commandUsage, parseCommon, usage } from '../cli/usage.mjs';
 import { buildCommunities } from '../graph/communities.mjs';
 import { graphSummary, readFreshIndex } from '../index/cache.mjs';
 import { buildCompactImpactReport, buildImpactReport } from '../impact/report.mjs';
+import { buildVectorImpactOverlay } from '../impact/vector-overlay.mjs';
+import { canonicalizeChangedPath } from '../impact/vector-profile.mjs';
 import { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from '../impact/format.mjs';
 
 const MAX_CHANGED_FILES = 20;
@@ -65,8 +67,10 @@ export async function runGraph(argv) {
     }
     usage(message, 'graph impact');
   }
+  if (isImpact) options.changed = [...new Set(options.changed.map((path) => canonicalizeChangedPath(options.root, path)).filter(Boolean))];
   const { status, index, metadata } = readFreshIndex(options.root);
-  const rawImpact = isImpact ? buildImpactReport(index, options.changed) : undefined;
+  const overlay = isImpact ? await buildVectorImpactOverlay(options.root, index, options.changed) : undefined;
+  const rawImpact = isImpact ? buildImpactReport(index, options.changed, { overlay, verboseSemantic: options.json }) : undefined;
   const impact = isImpact && (options.compact || options.yml) ? buildCompactImpactReport(rawImpact) : rawImpact;
   const payload = isImpact
     ? { ok: status.ok, command: 'graph impact', compact: options.compact || undefined, root: options.root, status, metadata, changed: options.changed[0], changedFiles: options.changed, related: impact.related, impact }

package/src/commands/query.mjs

@@ -3,7 +3,7 @@ import { usage } from '../cli/usage.mjs';
 import { readMemoryConfig } from '../memory/config.mjs';
 import { collectDocumentationChunks } from '../query/chunks.mjs';
 import { embedTexts } from '../query/embedder.mjs';
-import { readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, writeVectorCache } from '../query/store.mjs';
+import { isValidNormalizedVectorValues, readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, writeVectorCache } from '../query/store.mjs';
 
 const DEFAULT_LIMIT = 30;
 const MAX_LIMIT = 100;
@@ -31,10 +31,33 @@ export function parseQueryOptions(argv) {
   return options;
 }
 
-function cosine(left, vectors, offset) {
+function assertNormalizedVector(vector, label) {
+  if (!vector || vector.length !== VECTOR_DIMENSIONS || !isValidNormalizedVectorValues(vector)) throw new Error(`${label} must be a finite normalized ${VECTOR_DIMENSIONS}-dimensional vector.`);
+}
+
+export function cosineScore(left, vectors, offset = 0) {
+  assertNormalizedVector(left, 'Query vector');
+  const right = vectors?.subarray ? vectors.subarray(offset, offset + VECTOR_DIMENSIONS) : vectors?.slice(offset, offset + VECTOR_DIMENSIONS);
+  assertNormalizedVector(right, 'Passage vector');
   let score = 0;
-  for (let index = 0; index < VECTOR_DIMENSIONS; index += 1) score += left[index] * vectors[offset + index];
-  return score;
+  for (let index = 0; index < VECTOR_DIMENSIONS; index += 1) score += left[index] * right[index];
+  if (!Number.isFinite(score) || score < -1.000001 || score > 1.000001) throw new Error('Cosine similarity was outside the finite normalized range.');
+  return Math.max(-1, Math.min(1, score));
+}
+
+export function rankVectorFiles(queryVector, index) {
+  assertNormalizedVector(queryVector, 'Query vector');
+  if (!index || !Array.isArray(index.chunks) || index.vectors?.length !== index.chunks.length * VECTOR_DIMENSIONS || !isValidNormalizedVectorValues(index.vectors)) throw new Error('Vector index contains invalid passage vectors.');
+  const ranked = index.chunks.map((chunk, position) => ({ ...chunk, vectorScore: cosineScore(queryVector, index.vectors, position * VECTOR_DIMENSIONS) }))
+    .sort((left, right) => right.vectorScore - left.vectorScore || left.path.localeCompare(right.path) || left.id.localeCompare(right.id));
+  const results = [];
+  const seen = new Set();
+  for (const chunk of ranked) {
+    if (seen.has(chunk.path)) continue;
+    seen.add(chunk.path);
+    results.push(chunk);
+  }
+  return results;
 }
 
 function lexicalBoost(query, chunk) {
@@ -66,7 +89,11 @@ export async function buildVectorIndex(root, embed = embedTexts) {
   for (let offset = 0; offset < missing.length; offset += EMBED_BATCH_SIZE) {
     const batch = missing.slice(offset, offset + EMBED_BATCH_SIZE);
     const embedded = await embed(batch.map(({ chunk }) => `passage: ${chunk.passage}`));
-    embedded.forEach((vector, index) => vectors.set(vector, batch[index].index * VECTOR_DIMENSIONS));
+    if (!Array.isArray(embedded) || embedded.length !== batch.length) throw new Error('Embedder returned an unexpected passage-vector count.');
+    embedded.forEach((vector, index) => {
+      assertNormalizedVector(vector, 'Passage vector');
+      vectors.set(vector, batch[index].index * VECTOR_DIMENSIONS);
+    });
   }
   const storedChunks = chunks.map(({ passage, ...chunk }) => chunk);
   const manifest = writeVectorCache(root, storedChunks, vectors, {
@@ -81,9 +108,12 @@ export async function queryDocumentation(root, query, options = {}) {
   const embed = options.embed ?? embedTexts;
   const limit = options.limit ?? DEFAULT_LIMIT;
   const index = await buildVectorIndex(root, embed);
-  const [queryVector] = await embed([`query: ${query}`]);
+  const embeddedQuery = await embed([`query: ${query}`]);
+  if (!Array.isArray(embeddedQuery) || embeddedQuery.length !== 1) throw new Error('Embedder returned an unexpected query-vector count.');
+  const [queryVector] = embeddedQuery;
+  assertNormalizedVector(queryVector, 'Query vector');
   const rankedChunks = index.chunks.map((chunk, position) => {
-    const vectorScore = cosine(queryVector, index.vectors, position * VECTOR_DIMENSIONS);
+    const vectorScore = cosineScore(queryVector, index.vectors, position * VECTOR_DIMENSIONS);
     return { ...chunk, score: Number((vectorScore + lexicalBoost(query, chunk)).toFixed(6)), vectorScore: Number(vectorScore.toFixed(6)) };
   }).sort((left, right) => right.score - left.score || left.path.localeCompare(right.path));
   const results = [];

package/src/commands/traceability.mjs

@@ -3,6 +3,7 @@ import { join, resolve } from 'node:path';
 import { usage } from '../cli/usage.mjs';
 import { rel } from '../common/paths.mjs';
 import { extractDotdotgodTraceabilityBlocks, syncTraceabilityLinksInContent, validateTraceabilityLinksRegion } from '../docs/traceability.mjs';
+import { readMemoryConfig } from '../memory/config.mjs';
 
 function collectDocsMarkdownFiles(root) {
   const docs = join(root, 'docs');
@@ -43,15 +44,17 @@ export function parseTraceabilityOptions(argv) {
 
 export function runTraceability(argv) {
   const options = parseTraceabilityOptions(argv);
+  const config = readMemoryConfig(options.root);
   const files = collectDocsMarkdownFiles(options.root);
   const results = [];
-  const errors = [];
+  const errors = [...(config.errors ?? [])];
   for (const file of files) {
+    if (options.write && errors.length > 0) break;
     const content = readFileSync(file, 'utf8');
     for (const error of validateTraceabilityLinksRegion(content, options.root, file)) errors.push(error);
     const blocks = extractDotdotgodTraceabilityBlocks(content).filter((block) => !block.error);
     if (blocks.length === 0) continue;
-    const result = syncTraceabilityLinksInContent(content, blocks.at(-1).data, options.root, file);
+    const result = syncTraceabilityLinksInContent(content, blocks.at(-1).data, options.root, file, config);
     if (!result.ok) {
       for (const error of result.errors ?? []) errors.push(error);
       continue;

package/src/core.mjs

@@ -17,16 +17,18 @@ export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_LOAD_POLICY, DEFAULT_VALIDATION_
 export { buildCommunities, relationWeight } from './graph/communities.mjs';
 export { addEdge, addNode, compactGraph, expandGraph, graphStats, jsonSize, shardFile, writeJson } from './graph/store.mjs';
 export { cacheFile, collectIndexFiles, fingerprint, shouldIndexPath } from './index/files.mjs';
-export { buildMemoryAreas, buildPinnedFiles, detectCommandGuidance, detectPackageManager } from './memory/summary.mjs';
+export { buildMemoryAreas, detectCommandGuidance, detectPackageManager } from './memory/summary.mjs';
 export { isReadmeIndexPath, retrievalMetadataForPath } from './graph/metadata.mjs';
 export { buildGraph } from './graph/extract.mjs';
 export { addDeterministicSemanticEdges } from './graph/semantic.mjs';
 export { buildIndex, writeIndex, readIndex, getStatus, runIndex, runStatus, readFreshIndex, graphSummary } from './index/cache.mjs';
 export { runValidate } from './validate/run.mjs';
 export { buildImpactReport, buildCompactImpactReport } from './impact/report.mjs';
+export { buildChangedFileProfile, MAX_VECTOR_PROFILE_CHARS, MAX_VECTOR_PROFILE_FILE_BYTES, MAX_VECTOR_PROFILE_METADATA_ITEMS } from './impact/vector-profile.mjs';
+export { buildVectorImpactOverlay, VECTOR_RELATION_WEIGHT } from './impact/vector-overlay.mjs';
 export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from './impact/format.mjs';
 export { runConfig } from './commands/config.mjs';
-export { buildVectorIndex, parseQueryOptions, queryDocumentation, runQuery } from './commands/query.mjs';
+export { buildVectorIndex, cosineScore, parseQueryOptions, queryDocumentation, rankVectorFiles, runQuery } from './commands/query.mjs';
 export { chunkMarkdown, collectDocumentationChunks, collectDocumentationMarkdown, textFingerprint } from './query/chunks.mjs';
 export { readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, VECTOR_SCHEMA_VERSION, vectorCachePaths, writeVectorCache } from './query/store.mjs';
 export { extractBracketReferences, extractFuzzyReferences, normalizeReferenceAlias } from './reference/extract.mjs';

package/src/docs/traceability.mjs

@@ -1,20 +1,26 @@
 import { existsSync } from 'node:fs';
 import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { rel } from '../common/paths.mjs';
-import { defaultMemoryConfig, resolveMemoryArea } from '../memory/config.mjs';
+import { DEFAULT_TRACEABILITY_KEYS, defaultMemoryConfig, resolveMemoryArea } from '../memory/config.mjs';
 
 function isSecretIndexPath(path) {
   return /(^|\/)(\.env|\.npmrc|\.pypirc|id_rsa|id_dsa|id_ed25519|credentials|secrets?)(\.|\/|$)/i.test(path);
 }
 
-const TRACEABILITY_PATH_FIELDS = ['implementedBy', 'verifiedBy', 'relatedDocs'];
-const TRACEABILITY_COMMAND_FIELDS = ['verificationCommands'];
-const CONTRACT_ALLOWED_FIELDS = new Set(['id', 'title', 'sections', ...TRACEABILITY_PATH_FIELDS, ...TRACEABILITY_COMMAND_FIELDS]);
+function traceabilityKeys(config = defaultMemoryConfig()) {
+  return config.traceability?.keys ?? DEFAULT_TRACEABILITY_KEYS;
+}
+
+function traceabilityDefinitionMap(config = defaultMemoryConfig()) {
+  return new Map(traceabilityKeys(config).map((definition) => [definition.key, definition]));
+}
 export const TRACEABILITY_LINKS_START = '<!-- dotdotgod:traceability-links:start version=1 source=json-dotdotgod -->';
 export const TRACEABILITY_LINKS_END = '<!-- dotdotgod:traceability-links:end -->';
 
-export function traceabilityExample() {
-  return 'Expected dotdotgod traceability block:\n\n```json dotdotgod\n{\n  "kind": "spec",\n  "implementedBy": ["packages/..."],\n  "verifiedBy": ["packages/..."],\n  "relatedDocs": ["docs/..."],\n  "verificationCommands": ["pnpm ..."],\n  "contracts": [{\n    "id": "FEATURE-BEHAVIOR-001",\n    "title": "Focused behavior contract",\n    "sections": ["Focused Behavior"],\n    "implementedBy": ["packages/..."],\n    "verifiedBy": ["packages/..."],\n    "relatedDocs": ["docs/..."],\n    "verificationCommands": ["pnpm ..."]\n  }]\n}\n```\n\nProperty guidance:\n- kind: use "spec" for behavior specs.\n- implementedBy: source/config/script files that implement this spec\'s behavior.\n- verifiedBy: test files or verification docs that check this behavior.\n- relatedDocs: docs with relevant architecture, test strategy, or product context.\n- verificationCommands: commands an agent can run to verify this behavior.\n- contracts: optional focused behavior contracts; each contract requires non-empty id and title, may include sections as navigation hints, and may include the same path and command fields. Unknown contract fields are validation errors.';
+export function traceabilityExample(config = defaultMemoryConfig()) {
+  const fields = traceabilityKeys(config).map((definition) => `  "${definition.key}": [${definition.target === 'command' ? '"pnpm ..."' : '"packages/..."'}]`).join(',\n');
+  const guidance = traceabilityKeys(config).map((definition) => `- ${definition.key}: ${definition.description}`).join('\n');
+  return `Expected dotdotgod traceability block:\n\n\`\`\`json dotdotgod\n{\n  "kind": "spec"${fields ? `,\n${fields}` : ''}\n}\n\`\`\`\n\nProperty guidance:\n- kind: use "spec" for behavior specs.\n${guidance}${guidance ? '\n' : ''}- contracts: optional focused behavior contracts; each contract requires non-empty id and title, may include sections, and may include configured traceability fields. Unknown contract fields are validation errors.`;
 }
 
 function lineForOffset(content, offset) {
@@ -46,8 +52,8 @@ export function isLocalRelativeTraceabilityPath(value) {
   return !isSecretIndexPath(value);
 }
 
-function traceabilityFieldError(file, code, field, message, line = null) {
-  return { file, line, code, message: `${field ? `Field "${field}": ` : ''}${message}\nFix: update the traceability block so it matches the expected schema and points to existing project files or commands.\n\n${traceabilityExample()}` };
+function traceabilityFieldError(file, code, field, message, line = null, config = defaultMemoryConfig()) {
+  return { file, line, code, message: `${field ? `Field "${field}": ` : ''}${message}\nFix: update the traceability block so it matches the expected schema and points to existing project files or commands.\n\n${traceabilityExample(config)}` };
 }
 
 export function validateTraceabilityPlacement(content, root, file) {
@@ -124,12 +130,13 @@ function renderPathList(title, paths, root, file) {
   return lines;
 }
 
-function renderCommandList(commands) {
-  if (!Array.isArray(commands) || commands.length === 0) return [];
-  return ['- Verification commands:', ...commands.map((command) => `  - \`${escapeCodeSpan(command)}\``)];
+function renderDefinitionList(definition, values, root, file) {
+  if (!Array.isArray(values) || values.length === 0) return [];
+  if (definition.target === 'command') return [`- ${definition.label}:`, ...values.map((command) => `  - \`${escapeCodeSpan(command)}\``)];
+  return renderPathList(definition.label, values, root, file);
 }
 
-function renderContractList(contracts) {
+function renderContractList(contracts, definitions) {
   if (!Array.isArray(contracts) || contracts.length === 0) return [];
   const lines = ['- Contracts:'];
   for (const contract of contracts) {
@@ -138,23 +145,19 @@ function renderContractList(contracts) {
     const title = typeof contract.title === 'string' ? contract.title : '<missing-title>';
     const details = [];
     if (Array.isArray(contract.sections) && contract.sections.length > 0) details.push(`sections: ${contract.sections.length}`);
-    for (const [field, label] of [['implementedBy', 'impl'], ['verifiedBy', 'verify'], ['relatedDocs', 'docs'], ['verificationCommands', 'commands']]) {
-      if (Array.isArray(contract[field]) && contract[field].length > 0) details.push(`${label}: ${contract[field].length}`);
-    }
+    for (const definition of definitions) if (Array.isArray(contract[definition.key]) && contract[definition.key].length > 0) details.push(`${definition.key}: ${contract[definition.key].length}`);
     lines.push(`  - \`${escapeCodeSpan(id)}\` — ${escapeMarkdownText(title)}${details.length > 0 ? ` (${details.join(', ')})` : ''}`);
   }
   return lines;
 }
 
-export function renderTraceabilityLinks(data, root, file) {
+export function renderTraceabilityLinks(data, root, file, config = defaultMemoryConfig()) {
+  const definitions = traceabilityKeys(config);
   const body = [
     '### Traceability Links',
     '',
-    ...renderPathList('Implemented by', data?.implementedBy, root, file),
-    ...renderPathList('Verified by', data?.verifiedBy, root, file),
-    ...renderPathList('Related docs', data?.relatedDocs, root, file),
-    ...renderCommandList(data?.verificationCommands),
-    ...renderContractList(data?.contracts),
+    ...definitions.flatMap((definition) => renderDefinitionList(definition, data?.[definition.key], root, file)),
+    ...renderContractList(data?.contracts, definitions),
   ];
   return `${TRACEABILITY_LINKS_START}\n<!-- generated: do not edit manually -->\n\n${body.join('\n')}\n\n${TRACEABILITY_LINKS_END}`;
 }
@@ -163,10 +166,10 @@ export function renderCompactTraceabilityBlock(data) {
   return `\`\`\`json dotdotgod\n${JSON.stringify(data)}\n\`\`\``;
 }
 
-export function syncTraceabilityLinksInContent(content, data, root, file) {
+export function syncTraceabilityLinksInContent(content, data, root, file, config = defaultMemoryConfig()) {
   const region = findTraceabilityLinksRegion(content);
   if (region.status === 'invalid') return { ok: false, changed: false, errors: validateTraceabilityLinksRegion(content, root, file) };
-  const generated = renderTraceabilityLinks(data, root, file);
+  const generated = renderTraceabilityLinks(data, root, file, config);
   const blocks = extractDotdotgodTraceabilityBlocks(content).filter((block) => !block.error);
   if (blocks.length === 0) return { ok: false, changed: false, errors: [traceabilityFieldError(rel(root, file), 'TRACEABILITY_LINKS_MISSING_BLOCK', null, 'Cannot generate traceability links without a valid `json dotdotgod` block.')] };
   const block = blocks.at(-1);
@@ -216,12 +219,19 @@ function validateTraceabilityCommandArray(data, field, add, { required = true, d
   for (const value of data[field]) if (typeof value !== 'string' || value.trim().length === 0) add('TRACEABILITY_INVALID_COMMAND', displayField, `invalid command: ${JSON.stringify(value)}.`);
 }
 
+function validateConfiguredArray(data, definition, add, root, config, options) {
+  if (definition.target === 'command') validateTraceabilityCommandArray(data, definition.key, add, options);
+  else validateTraceabilityPathArray(data, definition.key, add, root, config, options);
+}
+
 function validateTraceabilityContracts(data, root, add, config) {
   if (data.contracts === undefined) return;
   if (!Array.isArray(data.contracts)) {
     add('TRACEABILITY_INVALID_FIELD', 'contracts', 'must be an array of focused contract objects.');
     return;
   }
+  const definitions = traceabilityKeys(config);
+  const allowedFields = new Set(['id', 'title', 'sections', ...definitions.map((definition) => definition.key)]);
   const ids = new Set();
   for (const [index, contract] of data.contracts.entries()) {
     const base = `contracts[${index}]`;
@@ -230,7 +240,7 @@ function validateTraceabilityContracts(data, root, add, config) {
       continue;
     }
     for (const field of Object.keys(contract)) {
-      if (!CONTRACT_ALLOWED_FIELDS.has(field)) add('TRACEABILITY_INVALID_FIELD', `${base}.${field}`, 'is not a supported contract field.');
+      if (!allowedFields.has(field)) add('TRACEABILITY_INVALID_FIELD', `${base}.${field}`, 'is not a supported contract field.');
     }
     if (typeof contract.id !== 'string' || contract.id.trim().length === 0) {
       add('TRACEABILITY_INVALID_FIELD', `${base}.id`, 'must be a non-empty stable contract ID string.');
@@ -246,21 +256,22 @@ function validateTraceabilityContracts(data, root, add, config) {
         if (typeof section !== 'string' || section.trim().length === 0) add('TRACEABILITY_INVALID_FIELD', `${base}.sections[${sectionIndex}]`, 'must be a non-empty heading title string.');
       }
     }
-    for (const field of TRACEABILITY_PATH_FIELDS) validateTraceabilityPathArray(contract, field, add, root, config, { required: false, displayField: `${base}.${field}` });
-    for (const field of TRACEABILITY_COMMAND_FIELDS) validateTraceabilityCommandArray(contract, field, add, { required: false, displayField: `${base}.${field}` });
+    for (const definition of definitions) validateConfiguredArray(contract, definition, add, root, config, { required: false, displayField: `${base}.${definition.key}` });
   }
 }
 
 export function validateTraceabilityBlock(data, root, file, line = null, config = defaultMemoryConfig()) {
   const errors = [];
-  const add = (code, field, message) => errors.push(traceabilityFieldError(rel(root, file), code, field, message, line));
+  const add = (code, field, message) => errors.push(traceabilityFieldError(rel(root, file), code, field, message, line, config));
   if (!data || typeof data !== 'object' || Array.isArray(data)) {
     add('TRACEABILITY_INVALID_JSON', null, 'Traceability block must be a JSON object.');
     return errors;
   }
   if (data.kind !== 'spec') add('TRACEABILITY_INVALID_KIND', 'kind', 'must be "spec" for behavior specs.');
-  for (const field of TRACEABILITY_PATH_FIELDS) validateTraceabilityPathArray(data, field, add, root, config);
-  for (const field of TRACEABILITY_COMMAND_FIELDS) validateTraceabilityCommandArray(data, field, add);
+  const definitions = traceabilityKeys(config);
+  const allowedFields = new Set(['kind', 'contracts', ...definitions.map((definition) => definition.key)]);
+  for (const field of Object.keys(data)) if (!allowedFields.has(field)) add('TRACEABILITY_INVALID_FIELD', field, 'is not configured as a traceability field.');
+  for (const definition of definitions) validateConfiguredArray(data, definition, add, root, config, { required: true, displayField: definition.key });
   validateTraceabilityContracts(data, root, add, config);
   return errors;
 }

package/src/graph/communities.mjs

@@ -43,8 +43,7 @@ function addBounded(list, value, limit) {
 export function relationWeight(relation) {
   if (relation === 'implemented_by' || relation === 'verified_by') return 4;
   if (relation === 'includes_resource' || relation === 'routes_to' || relation === 'related_doc' || relation === 'verification_command') return 3;
-  if (relation === 'links_to' || relation === 'belongs_to_area' || relation === 'declares_package' || relation === 'declares_bin' || relation === 'semantic_similarity') return 2;
-  if (relation === 'mentions_package') return 1;
+  if (relation === 'links_to' || relation === 'belongs_to_area' || relation === 'declares_package' || relation === 'declares_bin' || relation === 'vector_similarity') return 2;
   return 1;
 }
 

package/src/graph/metadata.mjs

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
 import { rel } from '../common/paths.mjs';
@@ -72,12 +73,21 @@ function contractNodeId(filePath, contractId) {
   return `contract:${filePath}#${contractId}`;
 }
 
-function addTraceabilityCommands(graph, sourceId, filePath, commands, idPrefix) {
-  for (const [index, command] of (Array.isArray(commands) ? commands : []).entries()) {
-    if (typeof command !== 'string' || command.trim().length === 0) continue;
-    const id = `verification_command:${idPrefix}#${index}`;
-    addNode(graph, id, 'verification_command', { command, path: filePath });
-    addEdge(graph, sourceId, id, 'verification_command', { confidence: 'CURATED_TRACEABILITY' });
+function traceabilityCommandId(sourceId, key, command) {
+  const digest = createHash('sha256').update(`${sourceId}\0${key}\0${command}`).digest('hex').slice(0, 16);
+  return `command:${key}:${digest}`;
+}
+
+function addTraceabilityValues(graph, sourceId, root, filePath, definition, values, config) {
+  for (const value of Array.isArray(values) ? values : []) {
+    if (definition.target === 'path') {
+      addTraceabilityTarget(graph, sourceId, root, definition.relation, value, { traceabilityKey: definition.key, relationWeight: definition.weight }, config);
+      continue;
+    }
+    if (typeof value !== 'string' || value.trim().length === 0) continue;
+    const id = traceabilityCommandId(sourceId, definition.key, value);
+    addNode(graph, id, 'command', { command: value, path: filePath, traceabilityKey: definition.key, relation: definition.relation });
+    addEdge(graph, sourceId, id, definition.relation, { confidence: 'CURATED_TRACEABILITY', traceabilityKey: definition.key, relationWeight: definition.weight });
   }
 }
 
@@ -91,10 +101,7 @@ function addTraceabilityContracts(graph, root, fileId, filePath, contracts, conf
     const sections = Array.isArray(contract.sections) ? contract.sections.filter((section) => typeof section === 'string' && section.trim().length > 0) : undefined;
     addNode(graph, id, 'contract', { path: filePath, contractId: contract.id, title: contract.title, sections });
     addEdge(graph, fileId, id, 'defines_contract', { confidence: 'CURATED_TRACEABILITY' });
-    for (const target of Array.isArray(contract.implementedBy) ? contract.implementedBy : []) addTraceabilityTarget(graph, id, root, 'implemented_by', target, {}, config);
-    for (const target of Array.isArray(contract.verifiedBy) ? contract.verifiedBy : []) addTraceabilityTarget(graph, id, root, 'verified_by', target, {}, config);
-    for (const target of Array.isArray(contract.relatedDocs) ? contract.relatedDocs : []) addTraceabilityTarget(graph, id, root, 'related_doc', target, {}, config);
-    addTraceabilityCommands(graph, id, filePath, Array.isArray(contract.verificationCommands) ? contract.verificationCommands : [], id);
+    for (const definition of config.traceability?.keys ?? []) addTraceabilityValues(graph, id, root, filePath, definition, contract[definition.key], config);
   }
 }
 
@@ -102,10 +109,7 @@ export function addTraceabilityGraph(root, fileId, content, graph, config = defa
   const filePath = fileId.replace(/^file:/, '');
   for (const block of extractDotdotgodTraceabilityBlocks(content)) {
     if (block.error || !block.data || block.data.kind !== 'spec') continue;
-    for (const target of block.data.implementedBy ?? []) addTraceabilityTarget(graph, fileId, root, 'implemented_by', target, {}, config);
-    for (const target of block.data.verifiedBy ?? []) addTraceabilityTarget(graph, fileId, root, 'verified_by', target, {}, config);
-    for (const target of block.data.relatedDocs ?? []) addTraceabilityTarget(graph, fileId, root, 'related_doc', target, {}, config);
-    addTraceabilityCommands(graph, fileId, filePath, block.data.verificationCommands, fileId);
+    for (const definition of config.traceability?.keys ?? []) addTraceabilityValues(graph, fileId, root, filePath, definition, block.data[definition.key], config);
     addTraceabilityContracts(graph, root, fileId, filePath, block.data.contracts, config);
   }
 }

package/src/graph/semantic.mjs

@@ -68,7 +68,7 @@ export function addDeterministicSemanticEdges(graph, config = defaultMemoryConfi
   const threshold = policy.semantic.threshold ?? 0.5;
   const topK = policy.semantic.topKPerFile ?? 5;
   const includeArchiveBodies = policy.semantic.includeArchiveBodies === true;
-  const enabledSignals = new Set(policy.semantic.signals ?? DEFAULT_IMPACT_RANKING_POLICY.semantic.signals);
+  const enabledSignals = new Set(policy.semantic.signals ?? ['path', 'filename', 'heading', 'package']);
   const baseGraph = { nodes: graph.nodes.map((node) => ({ ...node })), edges: graph.edges.filter((edge) => !SEMANTIC_RELATIONS.has(edge.relation)).map((edge) => ({ ...edge })) };
   const files = baseGraph.nodes.filter((node) => node.type === 'file' && node.path);
   const profiles = files.map((node) => semanticProfileForFile(node, baseGraph));

package/src/impact/format.mjs

@@ -69,8 +69,10 @@ export function formatYmlImpactOutput(payload, impact) {
     `  omitted_related: ${impact.omittedRelated ?? 0}`,
     '  ranking:',
     `    method: ${ymlScalar(impact.ranking?.method)}`,
-    `    preset: ${ymlScalar(impact.ranking?.preset)}`,
     `    config_source: ${ymlScalar(impact.ranking?.configSource)}`,
+    `    connection_cap: ${impact.ranking?.connectionCap ?? 80}`,
+    `    memory_cap: ${impact.ranking?.memoryCap ?? 20}`,
+    `    ppr_reference: ${impact.ranking?.pprReference ?? 0.4}`,
     '  per_seed:',
   ];
   for (const entry of impact.perSeed ?? []) {

package/src/impact/report.mjs

@@ -1,6 +1,8 @@
-import { DEFAULT_IMPACT_RANKING_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, defaultMemoryConfig } from '../memory/config.mjs';
+import { DEFAULT_IMPACT_RANKING_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, defaultMemoryConfig, traceabilityRelationWeights } from '../memory/config.mjs';
 import { retrievalMetadataForPath } from '../graph/metadata.mjs';
 import { buildPersonalizedPageRank, compareImpactItems, docsArea, hasCuratedImpactReason, isLowActionabilityImpactItem, isSemanticOnlyImpactItem, isTestPath, scoreImpactItem } from './scoring.mjs';
+import { normalizeChangedPath } from './vector-profile.mjs';
+import { MAX_VECTOR_EVIDENCE_CHUNK_ID_CHARS, MAX_VECTOR_EVIDENCE_HEADING_CHARS } from './vector-overlay.mjs';
 
 function addImpactItem(group, item, limit = 10) {
   if (group.items.some((existing) => existing.id === item.id)) return;
@@ -13,7 +15,7 @@ function addImpactItem(group, item, limit = 10) {
 
 function normalizeChangedPaths(changedPaths) {
   const values = Array.isArray(changedPaths) ? changedPaths : [changedPaths];
-  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+  return [...new Set(values.map(normalizeChangedPath).filter(Boolean))];
 }
 
 function selectImpactItems(sortedItems, maxRelated, seeds) {
@@ -48,9 +50,14 @@ function selectImpactItems(sortedItems, maxRelated, seeds) {
 }
 
 function buildCombinedImpactReport(index, changedPaths, limits = {}) {
-  const graph = index?.graph ?? { nodes: [], edges: [] };
+  const baseGraph = index?.graph ?? { nodes: [], edges: [] };
+  const overlay = limits.overlay ?? { status: 'disabled', edges: [] };
+  const graph = { nodes: baseGraph.nodes, edges: [...baseGraph.edges, ...(overlay.edges ?? [])] };
   const config = index?.memoryConfig ? { ...defaultMemoryConfig(), ...index.memoryConfig } : defaultMemoryConfig();
   const policy = cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY);
+  const traceabilityWeights = traceabilityRelationWeights(config.traceability);
+  policy.relationWeights = { ...policy.relationWeights, ...traceabilityWeights };
+  const curatedRelations = new Set(Object.keys(traceabilityWeights));
   const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
   const seeds = changedPaths.map((path) => `file:${path}`);
   const seedSet = new Set(seeds);
@@ -58,6 +65,7 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
   const groups = { files: { items: [], omitted: 0 }, docs: { items: [], omitted: 0 }, contracts: { items: [], omitted: 0 }, tests: { items: [], omitted: 0 }, commands: { items: [], omitted: 0 }, events: { items: [], omitted: 0 }, packageResources: { items: [], omitted: 0 }, symbols: { items: [], omitted: 0 } };
   const relatedIds = new Set(seeds);
   const reasons = new Map(seeds.map((seed) => [seed, new Set(['changed-file'])]));
+  const vectorEvidence = new Map();
   const addReason = (id, reason) => {
     relatedIds.add(id);
     if (!reasons.has(id)) reasons.set(id, new Set());
@@ -65,25 +73,31 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
   };
 
   for (const edge of graph.edges) {
+    if (edge.relation === 'vector_similarity' && seedSet.has(edge.source)) vectorEvidence.set(edge.target, {
+      score: edge.score,
+      heading: typeof edge.heading === 'string' ? edge.heading.slice(0, MAX_VECTOR_EVIDENCE_HEADING_CHARS) : undefined,
+      chunkId: typeof edge.chunkId === 'string' ? edge.chunkId.slice(0, MAX_VECTOR_EVIDENCE_CHUNK_ID_CHARS) : undefined,
+      confidence: edge.confidence,
+    });
     if (seedSet.has(edge.source)) addReason(edge.target, edge.relation);
     if (seedSet.has(edge.target)) addReason(edge.source, `incoming:${edge.relation}`);
   }
-  const expansionRelations = new Set(['implemented_by', 'verified_by', 'related_doc', 'verification_command', ...SEMANTIC_RELATIONS]);
+  const expansionRelations = new Set([...curatedRelations, ...SEMANTIC_RELATIONS]);
   for (const edge of graph.edges) {
     if (!expansionRelations.has(edge.relation)) continue;
     if (relatedIds.has(edge.source) && !seedSet.has(edge.target)) addReason(edge.target, edge.relation);
   }
 
   const pprScores = buildPersonalizedPageRank(graph, seeds, policy);
-  const candidatePprMax = Math.max(0, ...[...relatedIds].filter((id) => !seedSet.has(id)).map((id) => pprScores.get(id) ?? 0));
   const relatedAll = [...relatedIds].map((id) => {
     const node = nodeById.get(id) ?? { id };
     const path = node.path ?? id.replace(/^file:/, '').replace(/^test:/, '');
     const reasonList = [...(reasons.get(id) ?? [])];
     const retrieval = node.retrieval ?? retrievalMetadataForPath(path);
     const reasonSignals = reasonList.map((reason) => `reason:${reason}`);
-    const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores, candidatePprMax);
-    return { ...node, reasons: reasonList, retrieval: { ...retrieval, signals: [...new Set([...(retrieval.signals ?? []), ...reasonSignals])] }, ...scored };
+    const hasCuratedEvidence = reasonList.some((reason) => curatedRelations.has(reason.replace(/^incoming:/, '')));
+    const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores);
+    return { ...node, reasons: reasonList, hasCuratedEvidence, ...(vectorEvidence.has(id) ? { vectorEvidence: vectorEvidence.get(id) } : {}), retrieval: { ...retrieval, signals: [...new Set([...(retrieval.signals ?? []), ...reasonSignals])] }, ...scored };
   }).sort(compareImpactItems(seeds));
   const related = selectImpactItems(relatedAll, maxRelated, seeds);
   for (const item of related) {
@@ -98,7 +112,7 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
     else if (item.type === 'event') addImpactItem(groups.events, item, limits.events ?? 10);
     else if (item.type === 'package_resource') addImpactItem(groups.packageResources, item, limits.packageResources ?? 10);
   }
-  return { changed: changedPaths[0], changedFiles: changedPaths, ranking: { method: policy.ppr.enabled === false ? 'policy-score' : 'personalized-pagerank+policy', preset: policy.preset, configSource: index?.memoryConfig?.source ?? 'default', weights: policy.weights, ppr: policy.ppr }, related, groups, omittedRelated: Math.max(0, relatedAll.length - related.length) };
+  return { changed: changedPaths[0], changedFiles: changedPaths, semantic: { status: overlay.status ?? 'disabled', ...(limits.verboseSemantic ? { diagnostics: overlay.diagnostics } : {}) }, ranking: { method: 'weighted-personalized-pagerank+memory', configSource: index?.memoryConfig?.source ?? 'default', connectionCap: policy.connectionCap, memoryCap: policy.memoryCap, pprReference: policy.ppr.reference }, related, groups, omittedRelated: Math.max(0, relatedAll.length - related.length) };
 }
 
 export function buildImpactReport(index, changedPaths, limits = {}) {
@@ -106,7 +120,9 @@ export function buildImpactReport(index, changedPaths, limits = {}) {
   const aggregate = buildCombinedImpactReport(index, normalized, limits);
   const perSeedLimit = limits.perSeed ?? 5;
   aggregate.perSeed = normalized.map((changed) => {
-    const report = buildCombinedImpactReport(index, [changed], { ...limits, related: Math.max(limits.related ?? 25, perSeedLimit + 1) });
+    const seedId = `file:${changed}`;
+    const seedOverlay = limits.overlay ? { ...limits.overlay, edges: (limits.overlay.edges ?? []).filter((edge) => edge.source === seedId) } : undefined;
+    const report = buildCombinedImpactReport(index, [changed], { ...limits, overlay: seedOverlay, related: Math.max(limits.related ?? 25, perSeedLimit + 1) });
     const related = report.related.filter((item) => item.id !== `file:${changed}`).slice(0, perSeedLimit);
     return { changed, related, omittedRelated: Math.max(0, report.related.length - 1 - related.length) + report.omittedRelated };
   });
@@ -121,7 +137,7 @@ function compactScoreBreakdown(scoreBreakdown = {}) {
 
 export function compactImpactItem(item) {
   const compact = { id: item.id, type: item.type, impactScore: item.impactScore, reasons: (item.reasons ?? []).slice(0, 6), scoreBreakdown: compactScoreBreakdown(item.scoreBreakdown) };
-  for (const key of ['path', 'area', 'name', 'command', 'target', 'kind', 'specifier', 'title', 'contractId', 'sections']) if (item[key] !== undefined) compact[key] = item[key];
+  for (const key of ['path', 'area', 'name', 'command', 'target', 'kind', 'specifier', 'title', 'contractId', 'sections', 'vectorEvidence']) if (item[key] !== undefined) compact[key] = item[key];
   if (item.retrieval) compact.retrieval = { area: item.retrieval.area, role: item.retrieval.role, priority: item.retrieval.priority, freshness: item.retrieval.freshness };
   return compact;
 }
@@ -141,5 +157,5 @@ export function buildCompactImpactReport(impact, limits = {}) {
   const groups = Object.fromEntries(groupNames.map((name) => [name, compactImpactGroup(impact.groups?.[name], groupLimit)]));
   const perSeed = (impact.perSeed ?? []).map((entry) => ({ changed: entry.changed, related: (entry.related ?? []).slice(0, limits.perSeed ?? 5).map(compactImpactItem), omittedRelated: entry.omittedRelated ?? 0 }));
   const top10 = (impact.related ?? []).filter((item) => !seedIds.has(item.id)).slice(0, 10);
-  return { changed: impact.changed, changedFiles, perSeed, compact: true, ranking: { method: impact.ranking?.method, preset: impact.ranking?.preset, configSource: impact.ranking?.configSource }, related, groups, omittedRelated: (impact.omittedRelated ?? 0) + Math.max(0, (impact.related?.length ?? 0) - related.length), quality: { rawRelated: impact.related?.length ?? 0, compactRelated: related.length, semanticOnlyTop10: top10.filter((item) => isSemanticOnlyImpactItem(item)).length, curatedTop10: top10.filter((item) => hasCuratedImpactReason(item)).length, lowActionabilityTop10: top10.filter((item) => isLowActionabilityImpactItem(item)).length } };
+  return { changed: impact.changed, changedFiles, perSeed, semantic: impact.semantic, compact: true, ranking: { method: impact.ranking?.method, configSource: impact.ranking?.configSource, connectionCap: impact.ranking?.connectionCap, memoryCap: impact.ranking?.memoryCap, pprReference: impact.ranking?.pprReference }, related, groups, omittedRelated: (impact.omittedRelated ?? 0) + Math.max(0, (impact.related?.length ?? 0) - related.length), quality: { rawRelated: impact.related?.length ?? 0, compactRelated: related.length, semanticOnlyTop10: top10.filter((item) => isSemanticOnlyImpactItem(item)).length, curatedTop10: top10.filter((item) => hasCuratedImpactReason(item)).length, lowActionabilityTop10: top10.filter((item) => isLowActionabilityImpactItem(item)).length } };
 }