@dotdotgod/cli 0.2.14 → 0.2.17

package/README.md

@@ -38,9 +38,8 @@ 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.
-- `trello sync` plans or writes Trello linked-doc metadata from configured docs paths.
 
 ## Commands
 
@@ -77,7 +76,6 @@ dotdotgod graph communities .
 | Resolve `[[...]]` references from a prompt | `dotdotgod expand . "Update [[PLAN_MODE]]"` |
 | Repair generated traceability-link sections | `dotdotgod traceability links . --write` |
 | See what else to inspect after a change | `dotdotgod graph impact . --changed <path> --compact` |
-| Preview Trello linked-doc updates | `dotdotgod trello sync . --dry-run` |
 
 ## Changed-File Impact
 
@@ -87,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
 
@@ -121,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.14",
+  "version": "0.2.17",
   "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/cli/usage.mjs

@@ -42,20 +42,6 @@ Search shared project documentation with the local multilingual E5 vector index.
     case 'expand':
       return `Usage:
   dotdotgod expand <root> <prompt> [--max-results n] [--include-archive] [--with-impact] [--fuzzy] [--json]`;
-    case 'trello':
-      return `Usage:
-  dotdotgod trello sync <root> [--dry-run]`;
-    case 'trello sync':
-      return `Usage:
-  dotdotgod trello sync <root> [--dry-run]
-
-Options:
-  --dry-run  Preview planned Trello updates without calling Trello APIs.
-
-Write mode:
-  Omit --dry-run only in the trusted GitHub Actions default-branch push workflow.
-  Requires TRELLO_API_KEY and TRELLO_TOKEN in the trusted workflow environment.
-  Local/manual and pull request usage should run --dry-run.`;
     case 'traceability':
       return `Usage:
   dotdotgod traceability links <root> [--check|--write] [--json]`;
@@ -95,7 +81,6 @@ Commands:
   traceability links    Check or write generated traceability links.
   graph impact          Find files related to changed files.
   graph communities     Find groups of related project-memory nodes.
-  trello sync           Synchronize Trello cards and documentation.
 
 Options:
   -h, --help            Show help.
@@ -144,7 +129,6 @@ export function printVersion() {
 export function helpCommandFromArgs(args) {
   const nonHelp = args.filter((arg) => !isHelpToken(arg));
   if (nonHelp[0] === 'graph' && nonHelp[1]) return `graph ${nonHelp[1]}`;
-  if (nonHelp[0] === 'trello' && nonHelp[1]) return `trello ${nonHelp[1]}`;
   if (nonHelp[0] === 'traceability' && nonHelp[1]) return `traceability ${nonHelp[1]}`;
   if (nonHelp[0] === 'config' && nonHelp[1] === 'init') return 'config init';
   return nonHelp[0] ?? 'root';

package/src/commands/config.mjs

@@ -36,14 +36,16 @@ 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'}`);
   lines.push(`- plan mode writable paths: ${(payload.config.planMode?.writablePaths ?? []).join(', ') || 'none'}`);
-  lines.push(`- trello sync paths: ${(payload.config.integrations?.trello?.syncPaths ?? []).join(', ') || 'none'}`);
   const lowSignal = payload.config.referenceExpansion?.fuzzy?.lowSignal ?? { terms: [], add: [], remove: [] };
   lines.push(`- fuzzy low-signal terms: ${(lowSignal.terms ?? []).join(', ') || 'none'} (add: ${(lowSignal.add ?? []).join(', ') || 'none'}; remove: ${(lowSignal.remove ?? []).join(', ') || 'none'})`);
   if (errors.length > 0) {

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

@@ -7,40 +7,34 @@ import { runQuery } from './commands/query.mjs';
 import { runResolve, runExpand } from './reference/resolve.mjs';
 import { runTraceability } from './commands/traceability.mjs';
 import { runGraph } from './commands/graph.mjs';
-import { runTrelloSync } from './trello/sync.mjs';
 
 export { CACHE_VERSION } from './index/constants.mjs';
 export { commandUsage, hasHelpToken, helpCommandFromArgs, isHelpToken, isVersionToken, parseCommon, printVersion, usage } from './cli/usage.mjs';
 export { rel } from './common/paths.mjs';
 export { extractAnchors, extractFirstHeading, extractLinks, headingToAnchor, isKebabCase, isNumberedSeriesFilename, isUpperSnakeMarkdown, removeCodeBlocks, suggestFilenameFromHeading } from './docs/markdown.mjs';
 export { extractDotdotgodTraceabilityBlocks, findTraceabilityLinksRegion, isLocalRelativeTraceabilityPath, renderCompactTraceabilityBlock, stripTraceabilityLinksRegion, syncTraceabilityLinksInContent, traceabilityExample, validateTraceabilityBlock, validateTraceabilityLinksRegion, validateTraceabilityPlacement } from './docs/traceability.mjs';
-export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_INTEGRATIONS_POLICY, DEFAULT_LOAD_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneIntegrationsPolicy, cloneLoadPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, isSecretLikePathPattern, isValidPathPattern, matchPathPattern, memoryAreaForPath, memoryConfigSummary, normalizeLowSignalTerm, readMemoryConfig, requiresTraceability, resolveMemoryArea, trelloSyncPaths, validateMemoryConfigData } from './memory/config.mjs';
+export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_LOAD_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneLoadPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, isSecretLikePathPattern, isValidPathPattern, matchPathPattern, memoryAreaForPath, memoryConfigSummary, normalizeLowSignalTerm, readMemoryConfig, requiresTraceability, resolveMemoryArea, validateMemoryConfigData } from './memory/config.mjs';
 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';
 export { resolveReferenceCandidates, runResolve, runExpand } from './reference/resolve.mjs';
 export { parseTraceabilityOptions, runTraceability } from './commands/traceability.mjs';
 export { parseGraphOptions, runGraph } from './commands/graph.mjs';
-export { planTrelloDryRun, runTrelloSync } from './trello/sync.mjs';
-export { parseTrelloMetadata, extractTrelloShortLink } from './trello/metadata.mjs';
-export { normalizeGitHubRemote, resolveGitHubFileUrl, resolveGitHubRepositoryIdentity } from './trello/github-url.mjs';
-export { buildLinkedDocsData, summarizeTraceability } from './trello/summary.mjs';
-export { formatTrelloDryRunReport, formatTrelloWriteReport } from './trello/report.mjs';
-export { createTrelloClient, resolveTrelloCredentials } from './trello/client.mjs';
-export { customFieldTextValue, DEFAULT_DOTDOTGOD_CUSTOM_FIELD_NAME, dotdotgodCustomFieldName, mergeLinkedDocsCustomFieldValue, parseLinkedDocsCustomFieldPayload, serializeLinkedDocsCustomFieldPayload } from './trello/custom-fields.mjs';
 
 export async function runCli(argv = process.argv.slice(2)) {
   const [command = 'help', ...args] = argv;
@@ -58,13 +52,5 @@ export async function runCli(argv = process.argv.slice(2)) {
   else if (command === 'expand') runExpand(args);
   else if (command === 'traceability') runTraceability(args);
   else if (command === 'graph') await runGraph(args);
-  else if (command === 'trello') {
-    const result = await Promise.resolve(runTrelloSync(args));
-    if (result.stdout) process.stdout.write(result.stdout);
-    if (result.stderr) {
-      console.error(result.stderr);
-      console.error(commandUsage('trello'));
-    }
-    process.exit(result.exitCode);
-  } else usage(`Unknown command: ${command}`);
+  else usage(`Unknown command: ${command}`);
 }

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 ?? []) {