@dotdotgod/cli 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",
@@ -29,7 +29,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "leiden-ts": "^0.1.0"
+    "d3": "^7.9.0",
+    "graphology": "^0.26.0",
+    "leiden-ts": "^0.1.0",
+    "sigma": "^3.0.3"
   },
   "homepage": "https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli#readme",
   "repository": {

package/src/cli/usage.mjs

@@ -66,12 +66,18 @@ Checks or writes generated Markdown traceability link sections from canonical fe
     case 'graph':
       return `Usage:
   dotdotgod graph impact <root> --changed <path> [--changed <path> ...] [--compact|--json|--yml|--yaml]
+  dotdotgod graph serve <root> --changed <path> [--changed <path> ...] [--host HOST] [--port PORT]
   dotdotgod graph communities <root> [--json]`;
     case 'graph impact':
       return `Usage:
   dotdotgod graph impact <root> --changed <path> [--changed <path> ...] [--compact|--json|--yml|--yaml]
 
 Ranks nodes related to one or more changed files. <root> is the project root; repeat --changed with project-relative file paths. Results include a combined ranking and the top five related nodes for each changed file. Use --compact for a short text summary or --yml/--yaml for structured agent-facing output.`;
+    case 'graph serve':
+      return `Usage:
+  dotdotgod graph serve <root> --changed <path> [--changed <path> ...] [--host HOST] [--port PORT]
+
+Starts a local-only impact graph explorer. Changed files are rendered as root nodes and are excluded from related-result lists.`;
     case 'graph communities':
       return `Usage:
   dotdotgod graph communities <root> [--json]`;
@@ -95,6 +101,7 @@ Commands:
   status                Show local index status.
   traceability links    Check or write generated traceability links.
   graph impact          Find files related to changed files.
+  graph serve           Open a local impact graph explorer.
   graph communities     Find groups of related project-memory nodes.
 
 Options:

package/src/commands/graph.mjs

@@ -4,6 +4,7 @@ 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 { startImpactGraphServer } from '../graph-view/server.mjs';
 import { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from '../impact/format.mjs';
 
 const MAX_CHANGED_FILES = 20;
@@ -13,6 +14,8 @@ export function parseGraphOptions(argv) {
   const changed = [];
   let compact = false;
   let yml = false;
+  let host = '127.0.0.1';
+  let port = 0;
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === '--changed') {
       const next = argv[i + 1];
@@ -22,20 +25,33 @@ export function parseGraphOptions(argv) {
       }
     } else if (argv[i] === '--compact') compact = true;
     else if (argv[i] === '--yml' || argv[i] === '--yaml') yml = true;
+    else if (argv[i] === '--host' && argv[i + 1] && !argv[i + 1].startsWith('-')) { host = argv[i + 1]; i += 1; }
+    else if (argv[i] === '--port' && argv[i + 1] && !argv[i + 1].startsWith('-')) { port = Number(argv[i + 1]); i += 1; }
     else filtered.push(argv[i]);
   }
   const options = parseCommon(filtered);
   options.changed = [...new Set(changed)];
   options.compact = compact;
   options.yml = yml;
+  options.host = host;
+  options.port = Number.isInteger(port) && port >= 0 && port <= 65535 ? port : NaN;
   return options;
 }
 
 export async function runGraph(argv) {
   const sub = argv[0];
   const isImpact = sub === 'impact';
-  if (!['impact', 'communities'].includes(sub)) usage(sub ? `Unknown graph command: ${sub}` : 'Missing graph command.', 'graph');
+  const isServe = sub === 'serve';
+  if (!['impact', 'communities', 'serve'].includes(sub)) usage(sub ? `Unknown graph command: ${sub}` : 'Missing graph command.', 'graph');
   const options = parseGraphOptions(argv.slice(1));
+  if (isServe && options.changed.length === 0) usage('Missing required option: --changed <path>.', 'graph serve');
+  if (isServe && !Number.isInteger(options.port)) usage('Invalid --port. Use an integer from 0 through 65535.', 'graph serve');
+  if (isServe) {
+    options.changed = [...new Set(options.changed.map((path) => canonicalizeChangedPath(options.root, path)).filter(Boolean))];
+    const running = await startImpactGraphServer({ root: options.root, changed: options.changed, host: options.host, port: options.port });
+    console.log(`graph serve: ${running.url}`);
+    return;
+  }
   if (isImpact && [options.json, options.compact, options.yml].filter(Boolean).length > 1) {
     const message = 'Choose only one graph impact output mode: --compact, --json, or --yml/--yaml.';
     if (options.json) console.log(JSON.stringify({ ok: false, command: 'graph impact', compact: options.compact || undefined, yml: options.yml || undefined, root: options.root, error: { code: 'OUTPUT_MODE_CONFLICT', message }, usage: commandUsage('graph impact') }, null, 2));

package/src/core.mjs

@@ -28,6 +28,8 @@ 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 { buildImpactGraphPayload } from './graph-view/payload.mjs';
+export { buildServedImpact, startImpactGraphServer } from './graph-view/server.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';

package/src/docs/traceability.mjs

@@ -98,9 +98,11 @@ export function stripTraceabilityLinksRegion(content) {
   if (region.status === 'present') ranges.push({ start: region.start, end: region.end });
   for (const block of extractDotdotgodTraceabilityBlocks(content)) ranges.push({ start: block.index, end: block.end });
   if (ranges.length === 0) return content;
-  return ranges
+  const stripped = ranges
     .sort((a, b) => b.start - a.start)
     .reduce((next, range) => `${next.slice(0, range.start)}${next.slice(range.end)}`, content);
+  // Keep surrounding prose and one line separator, but not metadata headings or padding.
+  return stripped.replace(/(?:^[ \t]*\r?\n)*^##[ \t]+Traceability[ \t]*\r?(?:\n(?:[ \t]*\r?\n)*|$)/gm, '');
 }
 
 function markdownLinkPath(root, file, target) {

package/src/graph-view/assets/app.css

@@ -0,0 +1,111 @@
+:root {
+  color-scheme: light;
+  --paper: #f4f6f3;
+  --panel: #fbfcf8;
+  --ink: #182028;
+  --muted: #59656f;
+  --rule: #c8d0cd;
+  --cobalt: #1857c8;
+  --amber: #c66a12;
+  --green: #16734b;
+  --violet: #6b47a8;
+  --focus: #073f9b;
+  font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+* { box-sizing: border-box; }
+html, body { margin: 0; min-height: 100%; background: var(--paper); color: var(--ink); }
+body { min-height: 100vh; overflow: hidden; }
+button, input, select { font: inherit; }
+button { border: 1px solid var(--ink); background: var(--ink); color: #fff; padding: .62rem .82rem; cursor: pointer; }
+button:hover { background: var(--cobalt); border-color: var(--cobalt); }
+button:focus-visible, input:focus-visible, select:focus-visible, .result-button:focus-visible { outline: 3px solid color-mix(in srgb, var(--focus), transparent 25%); outline-offset: 2px; }
+::selection { background: var(--cobalt); color: white; }
+.command-rail { height: 64px; display: grid; grid-template-columns: 1fr minmax(420px, 620px) auto; align-items: center; gap: 1rem; padding: 0 1rem; border-bottom: 1px solid var(--ink); background: var(--panel); }
+.brand { display: flex; align-items: baseline; gap: .58rem; white-space: nowrap; }
+.brand strong { letter-spacing: -.025em; }
+.brand span:last-child { color: var(--muted); }
+.brand-mark { width: 12px; height: 12px; background: var(--cobalt); display: inline-block; }
+.reroot-form { display: grid; grid-template-columns: auto minmax(180px, 1fr) auto; align-items: center; gap: .55rem; }
+.reroot-form label { font-size: .76rem; font-weight: 750; text-transform: uppercase; letter-spacing: .07em; }
+.reroot-form input { min-width: 0; padding: .58rem .7rem; border: 1px solid var(--rule); background: white; color: var(--ink); }
+#status { margin: 0; color: var(--muted); font-size: .82rem; white-space: nowrap; }
+.workspace { height: calc(100vh - 64px); display: grid; grid-template-columns: 225px minmax(320px, 1fr) minmax(330px, 420px); }
+.filters, .evidence { background: var(--panel); overflow: auto; }
+.filters { border-right: 1px solid var(--rule); padding: 1.2rem 1rem; display: flex; flex-direction: column; gap: 1.3rem; }
+h1, h2, h3, p { margin-top: 0; }
+h1 { font-size: 1.42rem; margin-bottom: .42rem; letter-spacing: -.025em; }
+h2 { font-size: 1.12rem; margin-bottom: .2rem; }
+h3 { font-size: 1rem; }
+.filters p, .plot-heading p, .inspection p { color: var(--muted); font-size: .86rem; line-height: 1.5; }
+#relation-filters { border: 0; padding: 0; margin: 0; display: grid; gap: .35rem; }
+.filter-control { display: grid; grid-template-columns: 18px 1fr auto; align-items: center; gap: .48rem; padding: .42rem 0; border-bottom: 1px solid #e2e7e4; font-size: .82rem; }
+.filter-control input { accent-color: var(--cobalt); }
+.filter-control code { color: var(--muted); font-size: .7rem; }
+.motion-control { margin-top: .35rem; font-size: .72rem; font-weight: 700; text-transform: uppercase; letter-spacing: .05em; }
+#motion-mode { width: 100%; border: 1px solid var(--ink); border-radius: 0; background: var(--panel); color: var(--ink); padding: .52rem; }
+#skip-reveal { width: 100%; padding: .48rem .62rem; background: transparent; color: var(--ink); }
+.legend { display: grid; gap: .62rem; font-size: .78rem; }
+.legend span { display: flex; align-items: center; gap: .55rem; }
+.node-key { display: inline-block; width: 10px; height: 10px; border: 1px solid var(--ink); }
+.node-key.seed { background: var(--cobalt); }
+.node-key.doc { background: var(--violet); }
+.node-key.test { background: var(--green); }
+.node-key.code { background: #42515e; }
+.node-key.contract { background: var(--amber); }
+.node-key.heading { width: 7px; height: 7px; margin-inline: 1.5px; border-color: #66736d; background: #8b9690; }
+.reading-note { margin-top: auto; padding-top: 1rem; border-top: 1px solid var(--rule); }
+.plot { min-width: 0; position: relative; background-color: #edf1ee; background-image: linear-gradient(#dce3df 1px, transparent 1px), linear-gradient(90deg, #dce3df 1px, transparent 1px); background-size: 32px 32px; }
+.plot-heading { height: 58px; display: flex; justify-content: space-between; align-items: center; padding: .65rem .85rem; background: color-mix(in srgb, var(--panel), transparent 6%); border-bottom: 1px solid var(--rule); }
+.plot-heading p { margin-bottom: 0; }
+.plot-heading button { background: transparent; color: var(--ink); padding: .42rem .62rem; }
+#graph { width: 100%; height: calc(100% - 58px); }
+.graph-fallback { position: absolute; inset: 58px 0 0; place-items: center; padding: 2rem; text-align: center; background: var(--paper); color: var(--muted); }
+.graph-fallback:not([hidden]) { display: grid; }
+.evidence { border-left: 1px solid var(--rule); display: grid; grid-template-rows: auto auto minmax(180px, 1fr) auto; }
+.node-search { padding: 1rem; border-bottom: 1px solid var(--rule); }
+.node-search label { display: block; margin-bottom: .45rem; font-size: .76rem; font-weight: 750; text-transform: uppercase; letter-spacing: .06em; }
+.node-search input { width: 100%; padding: .58rem .7rem; border: 1px solid var(--rule); background: white; color: var(--ink); }
+.node-search-results { list-style: none; margin: .45rem 0 0; padding: 0; max-height: 11rem; overflow: auto; }
+.node-search-results:empty { display: none; }
+.node-search-results button { width: 100%; padding: .5rem; border: 0; border-bottom: 1px solid #e2e7e4; background: transparent; color: var(--ink); text-align: left; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: .72rem; overflow-wrap: anywhere; }
+.node-search-results button:hover { background: #e5ecfa; color: var(--ink); }
+.evidence-heading { display: flex; justify-content: space-between; align-items: baseline; padding: 1rem; border-bottom: 1px solid var(--rule); }
+.evidence-heading h2 { margin: 0; }
+#result-count { color: var(--muted); font-variant-numeric: tabular-nums; font-size: .78rem; }
+.result-list { list-style: none; margin: 0; padding: 0; overflow: auto; }
+.result-button { width: 100%; display: grid; grid-template-columns: 2.2rem 1fr auto; gap: .62rem; align-items: start; padding: .75rem 1rem; border: 0; border-bottom: 1px solid #dce2df; background: transparent; color: var(--ink); text-align: left; }
+.result-button:hover, .result-button[aria-current="true"] { background: #e5ecfa; color: var(--ink); }
+.rank { color: var(--muted); font-variant-numeric: tabular-nums; }
+.result-copy { min-width: 0; }
+.result-path { display: block; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: .76rem; overflow-wrap: anywhere; }
+.result-reason { display: block; color: var(--muted); font-size: .72rem; margin-top: .26rem; }
+.score { color: var(--cobalt); font-weight: 800; font-variant-numeric: tabular-nums; }
+.inspection { border-top: 1px solid var(--ink); padding: 1rem; max-height: 38vh; overflow: auto; background: #f7f8f4; }
+.inspection dl { display: grid; grid-template-columns: 6.8rem 1fr; gap: .45rem .75rem; margin: 0; font-size: .78rem; }
+.inspection dt { color: var(--muted); }
+.inspection dd { margin: 0; overflow-wrap: anywhere; }
+.inspection .reroot-selected { margin-top: 1rem; width: 100%; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; }
+@media (max-width: 1050px) {
+  body { overflow: auto; }
+  .command-rail { height: auto; min-height: 64px; grid-template-columns: 1fr auto; padding-block: .65rem; }
+  .reroot-form { grid-column: 1 / -1; grid-row: 2; }
+  .workspace { height: auto; min-height: calc(100vh - 110px); grid-template-columns: 190px minmax(300px, 1fr); }
+  .evidence { grid-column: 1 / -1; border-left: 0; border-top: 1px solid var(--ink); grid-template-rows: auto auto minmax(220px, 42vh) auto; }
+  .plot { min-height: 620px; }
+}
+@media (max-width: 680px) {
+  .command-rail { display: flex; flex-wrap: wrap; }
+  .brand { flex: 1; }
+  #status { width: 100%; }
+  .reroot-form { width: 100%; grid-template-columns: 1fr auto; }
+  .reroot-form label { grid-column: 1 / -1; }
+  .workspace { display: flex; flex-direction: column; }
+  .filters { border-right: 0; border-bottom: 1px solid var(--rule); }
+  #relation-filters { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .legend { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .reading-note { margin-top: 0; }
+  .plot { min-height: 60vh; }
+  .evidence { min-height: 70vh; }
+}
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { scroll-behavior: auto !important; transition: none !important; animation: none !important; } }

package/src/graph-view/assets/app.js

@@ -0,0 +1,244 @@
+(() => {
+  const COLORS = { seed: '#1857c8', doc: '#6b47a8', test: '#16734b', code: '#42515e', contract: '#c66a12', heading: '#8b9690', other: '#66727b' };
+  const MORPH_DURATION = 380;
+  const MOTION_MODES = new Set(['instant', 'layer', 'sequence']);
+  const savedMotionMode = localStorage.getItem('dotdotgod:graph-motion');
+  const state = { payload: null, renderer: null, graph: null, selected: null, enabledRelations: new Set(), previousPositions: new Map(), animationFrame: null, positioned: [], firstRender: true, motionMode: MOTION_MODES.has(savedMotionMode) ? savedMotionMode : 'layer', revealToken: 0 };
+  const elements = {
+    graph: document.querySelector('#graph'), fallback: document.querySelector('#graph-fallback'), filters: document.querySelector('#relation-filters'), motionMode: document.querySelector('#motion-mode'), skipReveal: document.querySelector('#skip-reveal'), list: document.querySelector('#result-list'), inspection: document.querySelector('#inspection'), status: document.querySelector('#status'), summary: document.querySelector('#plot-summary'), count: document.querySelector('#result-count'), form: document.querySelector('#reroot-form'), input: document.querySelector('#reroot-path'), reset: document.querySelector('#reset-camera'), search: document.querySelector('#node-search-input'), searchResults: document.querySelector('#node-search-results'),
+  };
+
+  function nodeKind(node) {
+    if (node.seed) return 'seed';
+    if (node.type === 'contract') return 'contract';
+    if (node.type === 'heading' || node.id.startsWith('heading:')) return 'heading';
+    if (node.path?.startsWith('docs/')) return 'doc';
+    if (/(^|\/)(test|tests)\//.test(node.path ?? '') || /\.(test|spec)\./.test(node.path ?? '')) return 'test';
+    if (node.type === 'file') return 'code';
+    return 'other';
+  }
+
+  function relationLabel(value) { return value.replace(/^incoming:/, '').replaceAll('_', ' '); }
+  function safe(value) { const span = document.createElement('span'); span.textContent = value ?? ''; return span.innerHTML; }
+
+  function layoutNodes(nodes, edges) {
+    const width = Math.max(elements.graph.clientWidth, 600);
+    const height = Math.max(elements.graph.clientHeight, 500);
+    const center = { x: width / 2, y: height / 2 };
+    const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+    const layerCounts = new Map();
+    const simulationNodes = [...nodes].sort((left, right) => left.depth - right.depth || left.id.localeCompare(right.id)).map((node) => {
+      const layerIndex = layerCounts.get(node.depth) ?? 0;
+      layerCounts.set(node.depth, layerIndex + 1);
+      const radius = node.depth === 0 ? Math.min(34, nodes.filter((candidate) => candidate.depth === 0).length * 8) : 66 + node.depth * 76;
+      const angle = layerIndex * goldenAngle + node.depth * .35;
+      return { ...node, targetX: center.x + Math.cos(angle) * radius, targetY: center.y + Math.sin(angle) * radius, x: center.x + Math.cos(angle) * radius, y: center.y + Math.sin(angle) * radius };
+    });
+    const byId = new Map(simulationNodes.map((node) => [node.id, node]));
+    const simulationEdges = edges.map((edge) => ({ ...edge, source: byId.get(edge.source), target: byId.get(edge.target) })).filter((edge) => edge.source && edge.target);
+    const simulation = d3.forceSimulation(simulationNodes)
+      .force('charge', d3.forceManyBody().strength((node) => node.type === 'heading' ? -16 : node.seed ? -220 : -48))
+      .force('link', d3.forceLink(simulationEdges).id((node) => node.id).distance((edge) => edge.relation === 'contains_heading' ? 18 : edge.source.seed || edge.target.seed ? 72 : 38).strength((edge) => edge.relation === 'contains_heading' ? .72 : .34))
+      .force('x', d3.forceX((node) => node.targetX).strength(.16))
+      .force('y', d3.forceY((node) => node.targetY).strength(.16))
+      .force('center', d3.forceCenter(width / 2, height / 2).strength(.025))
+      .force('collide', d3.forceCollide().radius((node) => node.type === 'heading' ? 3.5 : 6 + Math.sqrt(node.impactScore || 0)))
+      .stop();
+    const ticks = nodes.length > 1400 ? 70 : nodes.length > 700 ? 100 : nodes.length > 300 ? 130 : 180;
+    for (let index = 0; index < ticks; index += 1) simulation.tick();
+    return simulationNodes;
+  }
+
+  function visibleModel() {
+    const sourceNodes = state.payload.graph.nodes;
+    const sourceIds = new Set(sourceNodes.map((node) => node.id));
+    return { nodes: sourceNodes, edges: state.payload.graph.edges.filter((edge) => state.enabledRelations.has(edge.relation) && sourceIds.has(edge.source) && sourceIds.has(edge.target)) };
+  }
+
+  function revealDelay(node, index, maximumDepth, totalNodes) {
+    if (!state.firstRender || state.motionMode === 'instant') return 0;
+    if (state.motionMode === 'sequence') return index * Math.min(32, 1200 / Math.max(totalNodes, 1));
+    return node.depth * Math.min(70, 650 / Math.max(maximumDepth, 1));
+  }
+
+  function finishReveal(positioned) {
+    cancelAnimationFrame(state.animationFrame);
+    state.revealToken += 1;
+    for (const node of positioned) {
+      if (!state.graph?.hasNode(node.id)) continue;
+      state.graph.setNodeAttribute(node.id, 'x', node.x);
+      state.graph.setNodeAttribute(node.id, 'y', node.y);
+      state.graph.setNodeAttribute(node.id, 'size', node.renderSize ?? 4);
+    }
+    state.renderer?.refresh();
+    state.previousPositions = new Map(positioned.map((node) => [node.id, { x: node.x, y: node.y }]));
+    state.firstRender = false;
+    elements.skipReveal.hidden = true;
+  }
+
+  function animatePositions(graph, positioned) {
+    cancelAnimationFrame(state.animationFrame);
+    const token = ++state.revealToken;
+    const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
+    const mode = reduced ? 'instant' : state.motionMode;
+    const maximumDepth = Math.max(0, ...positioned.map((node) => node.depth));
+    const ordered = [...positioned].sort((left, right) => left.depth - right.depth || left.id.localeCompare(right.id));
+    const orderById = new Map(ordered.map((node, index) => [node.id, index]));
+    const starts = new Map(positioned.map((node) => {
+      const prior = state.previousPositions.get(node.id);
+      const root = positioned.find((candidate) => candidate.id === node.nearestRoot);
+      return [node.id, prior ?? { x: root?.x ?? node.x, y: root?.y ?? node.y }];
+    }));
+    const lastDelay = mode === 'instant' ? 0 : Math.max(0, ...positioned.map((node) => revealDelay(node, orderById.get(node.id), maximumDepth, positioned.length)));
+    const duration = mode === 'instant' ? 0 : MORPH_DURATION + lastDelay;
+    const startedAt = performance.now();
+    elements.skipReveal.hidden = duration === 0;
+    const tick = (now) => {
+      if (token !== state.revealToken) return;
+      const elapsed = now - startedAt;
+      for (const node of positioned) {
+        const delay = mode === 'instant' ? 0 : revealDelay(node, orderById.get(node.id), maximumDepth, positioned.length);
+        const progress = duration === 0 ? 1 : Math.max(0, Math.min(1, (elapsed - delay) / MORPH_DURATION));
+        const eased = 1 - Math.pow(1 - progress, 4);
+        const start = starts.get(node.id);
+        graph.setNodeAttribute(node.id, 'x', start.x + (node.x - start.x) * eased);
+        graph.setNodeAttribute(node.id, 'y', start.y + (node.y - start.y) * eased);
+        graph.setNodeAttribute(node.id, 'size', (node.renderSize ?? 4) * (progress === 0 ? 0 : .18 + .82 * eased));
+      }
+      state.renderer?.refresh();
+      if (elapsed < duration) state.animationFrame = requestAnimationFrame(tick);
+      else finishReveal(positioned);
+    };
+    state.animationFrame = requestAnimationFrame(tick);
+  }
+
+  function renderFilters(edges) {
+    const relations = [...new Set(edges.map((edge) => edge.relation))].sort();
+    const previous = state.enabledRelations;
+    state.enabledRelations = new Set(relations.filter((relation) => previous.size === 0 || previous.has(relation)));
+    elements.filters.replaceChildren(...relations.map((relation) => {
+      const label = document.createElement('label'); label.className = 'filter-control';
+      const input = document.createElement('input'); input.type = 'checkbox'; input.checked = state.enabledRelations.has(relation); input.value = relation;
+      input.addEventListener('change', () => { input.checked ? state.enabledRelations.add(relation) : state.enabledRelations.delete(relation); renderGraph(); });
+      const text = document.createElement('span'); text.textContent = relationLabel(relation);
+      const count = document.createElement('code'); count.textContent = String(edges.filter((edge) => edge.relation === relation).length);
+      label.append(input, text, count); return label;
+    }));
+  }
+
+  function renderGraph() {
+    if (state.graph) state.previousPositions = new Map(state.graph.nodes().map((id) => [id, { x: state.graph.getNodeAttribute(id, 'x'), y: state.graph.getNodeAttribute(id, 'y') }]));
+    cancelAnimationFrame(state.animationFrame);
+    state.renderer?.kill();
+    const model = visibleModel();
+    const visibleNodes = model.nodes;
+    const positioned = layoutNodes(visibleNodes, model.edges);
+    state.positioned = positioned;
+    try {
+      const graph = new graphology.MultiDirectedGraph();
+      for (const node of positioned) {
+        node.renderSize = node.seed ? 14 : node.type === 'heading' ? 2 : 4 + Math.sqrt(Math.max(node.impactScore, 1)) * .55;
+        const start = state.previousPositions.get(node.id) ?? positioned.find((candidate) => candidate.id === node.nearestRoot) ?? node;
+        graph.addNode(node.id, { label: node.label, x: start.x, y: start.y, size: node.renderSize, color: COLORS[nodeKind(node)], node });
+      }
+      model.edges.forEach((edge, index) => graph.addDirectedEdgeWithKey(`edge-${index}`, edge.source, edge.target, { color: edge.relation === 'vector_similarity' ? '#c66a12' : '#9ca8a3', size: edge.weight ? Math.min(3, 1 + edge.weight / 7) : 1, type: 'arrow', relation: edge.relation }));
+      state.graph = graph;
+      state.renderer = new Sigma(graph, elements.graph, { renderEdgeLabels: false, labelDensity: visibleNodes.length > 500 ? .03 : .1, labelRenderedSizeThreshold: visibleNodes.length > 500 ? 11 : 7, defaultEdgeType: 'arrow', zIndex: true, nodeReducer: (id, data) => {
+        if (!state.selected || !state.graph.hasNode(state.selected)) return data;
+        const neighbors = new Set(state.graph.neighbors(state.selected));
+        if (id === state.selected || neighbors.has(id)) return { ...data, highlighted: true, zIndex: 2 };
+        return { ...data, color: '#cbd1ce', label: '', zIndex: 0 };
+      }, edgeReducer: (key, data) => {
+        if (!state.selected || !state.graph.hasNode(state.selected)) return data;
+        const [source, target] = state.graph.extremities(key);
+        return source === state.selected || target === state.selected ? { ...data, color: '#1857c8', size: 2.4, zIndex: 2 } : { ...data, color: '#d8dedb', zIndex: 0 };
+      } });
+      state.renderer.on('clickNode', ({ node }) => selectNode(node, true));
+      animatePositions(graph, positioned);
+      elements.fallback.hidden = true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error('Impact graph rendering failed:', error);
+      elements.fallback.textContent = `Graph rendering failed: ${message}`;
+      elements.fallback.hidden = false;
+    }
+  }
+
+  function renderList() {
+    const related = state.payload.impact.related;
+    elements.count.textContent = `${related.length} results`;
+    elements.list.replaceChildren(...related.map((item, index) => {
+      const entry = document.createElement('li');
+      const button = document.createElement('button'); button.type = 'button'; button.className = 'result-button'; button.dataset.nodeId = item.id; button.setAttribute('aria-current', item.id === state.selected ? 'true' : 'false');
+      button.innerHTML = `<span class="rank">${String(index + 1).padStart(2, '0')}</span><span class="result-copy"><span class="result-path">${safe(item.path ?? item.title ?? item.id)}</span><span class="result-reason">${safe((item.reasons ?? []).slice(0, 2).map(relationLabel).join(' · '))}</span></span><span class="score">${item.impactScore}</span>`;
+      button.addEventListener('click', () => selectNode(item.id, true)); entry.append(button); return entry;
+    }));
+  }
+
+  function renderSearch() {
+    const query = elements.search.value.trim().toLocaleLowerCase();
+    if (!query) { elements.searchResults.replaceChildren(); return; }
+    const matches = state.payload.graph.nodes.filter((node) => `${node.label} ${node.path ?? ''} ${node.id}`.toLocaleLowerCase().includes(query)).slice(0, 30);
+    elements.searchResults.replaceChildren(...matches.map((node) => {
+      const item = document.createElement('li'); const button = document.createElement('button'); button.type = 'button'; button.textContent = node.label ?? node.id;
+      button.addEventListener('click', () => { selectNode(node.id); elements.searchResults.replaceChildren(); });
+      item.append(button); return item;
+    }));
+  }
+
+  function renderInspection(node) {
+    if (!node) return;
+    const score = node.seed ? 100 : node.impactScore;
+    const reasons = (node.reasons ?? []).map(relationLabel).join(', ') || 'whole graph node';
+    const ppr = node.scoreBreakdown?.connection?.ppr;
+    const memory = node.scoreBreakdown?.memory;
+    elements.inspection.innerHTML = `<h3>${safe(node.label ?? node.path ?? node.id)}</h3><dl><dt>Type</dt><dd>${safe(node.type)}</dd><dt>Impact score</dt><dd>${safe(String(score))}</dd><dt>Evidence</dt><dd>${safe(reasons)}</dd><dt>Component</dt><dd>${safe(String((node.component ?? 0) + 1))}</dd>${ppr !== undefined ? `<dt>PPR contribution</dt><dd>${safe(String(ppr))}</dd>` : ''}${memory ? `<dt>Memory contribution</dt><dd>${safe(String((memory.priority ?? 0) + (memory.policyAdjustments ?? 0)))}</dd>` : ''}${node.vectorEvidence?.score ? `<dt>Similarity</dt><dd>${safe(String(node.vectorEvidence.score))}</dd>` : ''}<dt>Path</dt><dd>${safe(node.path ?? node.id)}</dd></dl>${node.path && !node.seed ? '<button type="button" class="reroot-selected">Re-root from this file</button>' : ''}`;
+    elements.inspection.querySelector('.reroot-selected')?.addEventListener('click', () => loadImpact([node.path]));
+  }
+
+  function selectNode(id, focusList = false) {
+    state.selected = id;
+    state.renderer?.refresh();
+    for (const button of elements.list.querySelectorAll('.result-button')) button.setAttribute('aria-current', button.dataset.nodeId === id ? 'true' : 'false');
+    if (focusList) elements.list.querySelector(`[data-node-id="${CSS.escape(id)}"]`)?.scrollIntoView({ block: 'nearest' });
+    renderInspection(state.payload.graph.nodes.find((node) => node.id === id));
+    history.replaceState(null, '', `#${encodeURIComponent(id)}`);
+  }
+
+  async function loadImpact(paths) {
+    elements.status.textContent = 'Calculating impact…';
+    const query = paths.map((path) => `changed=${encodeURIComponent(path)}`).join('&');
+    const response = await fetch(`/api/reroot?${query}`);
+    const payload = await response.json();
+    if (!response.ok || !payload.ok) { elements.status.textContent = payload.error?.message ?? 'Impact calculation failed.'; return; }
+    applyPayload(payload);
+  }
+
+  function applyPayload(payload) {
+    state.payload = payload;
+    state.selected = payload.graph.changedFiles.length === 1 ? `file:${payload.graph.changedFiles[0]}` : null;
+    elements.input.value = payload.graph.changedFiles[0] ?? '';
+    elements.status.textContent = payload.impact.semantic.status === 'available' ? 'Shared structural graph · semantic ranking available' : 'Shared structural graph · structural ranking';
+    const omitted = payload.graph.diagnostics?.disconnectedNodesOmitted ?? 0;
+    const depth = payload.graph.diagnostics?.maximumDepth ?? 0;
+    elements.summary.textContent = `${payload.graph.nodes.length} connected nodes · ${payload.graph.edges.length} relations · ${depth} hops · ${omitted} disconnected omitted`;
+    renderFilters(payload.graph.edges); renderGraph(); renderList(); renderSearch();
+    if (state.selected && payload.graph.nodes.some((node) => node.id === state.selected)) renderInspection(payload.graph.nodes.find((node) => node.id === state.selected));
+    else if (payload.graph.nodes.length === 0) elements.inspection.innerHTML = '<h3>No shared structural nodes</h3><p>Add indexable shared files or relations to populate this graph. Local memory and headings are intentionally hidden.</p>';
+  }
+
+  elements.motionMode.value = state.motionMode;
+  elements.motionMode.addEventListener('change', () => {
+    state.motionMode = MOTION_MODES.has(elements.motionMode.value) ? elements.motionMode.value : 'layer';
+    localStorage.setItem('dotdotgod:graph-motion', state.motionMode);
+    state.firstRender = true;
+    state.previousPositions.clear();
+    renderGraph();
+  });
+  elements.skipReveal.addEventListener('click', () => finishReveal(state.positioned));
+  elements.form.addEventListener('submit', (event) => { event.preventDefault(); const path = elements.input.value.trim(); if (path) loadImpact([path]); });
+  elements.reset.addEventListener('click', () => state.renderer?.getCamera().animatedReset({ duration: matchMedia('(prefers-reduced-motion: reduce)').matches ? 0 : 250 }));
+  elements.search.addEventListener('input', renderSearch);
+  addEventListener('resize', () => state.renderer?.refresh());
+  fetch('/api/impact').then((response) => response.json()).then(applyPayload).catch((error) => { console.error(error); elements.status.textContent = 'Unable to load impact data.'; });
+})();

package/src/graph-view/assets/index.html

@@ -0,0 +1,73 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>dotdotgod structural graph</title>
+  <link rel="stylesheet" href="/app.css">
+</head>
+<body>
+  <header class="command-rail">
+    <div class="brand"><span class="brand-mark" aria-hidden="true"></span><strong>dotdotgod</strong><span>structural graph</span></div>
+    <form id="reroot-form" class="reroot-form">
+      <label for="reroot-path">Re-root graph</label>
+      <input id="reroot-path" name="changed" autocomplete="off" placeholder="packages/cli/src/core.mjs">
+      <button type="submit">Inspect file</button>
+    </form>
+    <p id="status" role="status">Loading impact data…</p>
+  </header>
+
+  <main class="workspace">
+    <aside class="filters" aria-labelledby="filters-title">
+      <div>
+        <h1 id="filters-title">Relation signals</h1>
+        <p>Filter what is drawn without changing the impact ranking.</p>
+      </div>
+      <fieldset id="relation-filters"><legend class="sr-only">Visible relation types</legend></fieldset>
+      <label class="motion-control" for="motion-mode">Node reveal</label>
+      <select id="motion-mode">
+        <option value="instant">Instant</option>
+        <option value="layer">By hop layer</option>
+        <option value="sequence">One by one</option>
+      </select>
+      <button id="skip-reveal" type="button" hidden>Skip reveal</button>
+      <div class="legend" aria-label="Node legend">
+        <span><i class="node-key seed"></i>Changed root</span>
+        <span><i class="node-key doc"></i>Documentation</span>
+        <span><i class="node-key test"></i>Verification</span>
+        <span><i class="node-key code"></i>Source</span>
+        <span><i class="node-key contract"></i>Contract</span>
+        <span><i class="node-key heading"></i>Heading</span>
+      </div>
+      <p class="reading-note">The graph grows outward from changed-file roots by structural hop. Position is layout only, never rank.</p>
+    </aside>
+
+    <section class="plot" aria-labelledby="plot-title">
+      <div class="plot-heading">
+        <div><h2 id="plot-title">Impact field</h2><p id="plot-summary"></p></div>
+        <button id="reset-camera" type="button">Reset view</button>
+      </div>
+      <div id="graph" aria-hidden="true"></div>
+      <div id="graph-fallback" class="graph-fallback" hidden>WebGL is unavailable. Use the synchronized ranked list.</div>
+    </section>
+
+    <aside class="evidence" aria-labelledby="evidence-title">
+      <section class="node-search" aria-labelledby="node-search-title">
+        <label id="node-search-title" for="node-search-input">Search shared graph nodes</label>
+        <input id="node-search-input" type="search" autocomplete="off" placeholder="Path, title, or node ID" aria-controls="node-search-results">
+        <ul id="node-search-results" class="node-search-results"></ul>
+      </section>
+      <div class="evidence-heading"><h2 id="evidence-title">Ranked evidence</h2><span id="result-count"></span></div>
+      <ol id="result-list" class="result-list"></ol>
+      <section id="inspection" class="inspection" aria-live="polite">
+        <h3>Select an impacted file</h3>
+        <p>The graph and ranked list share one selection. Details will appear here.</p>
+      </section>
+    </aside>
+  </main>
+  <script src="/vendor/graphology.js"></script>
+  <script src="/vendor/sigma.js"></script>
+  <script src="/vendor/d3.js"></script>
+  <script src="/app.js"></script>
+</body>
+</html>

package/src/graph-view/payload.mjs

@@ -0,0 +1,114 @@
+import { resolveMemoryArea } from '../memory/config.mjs';
+
+function edgeKey(edge) {
+  return `${edge.source}\0${edge.target}\0${edge.relation}`;
+}
+
+function labelForNode(node) {
+  if (node.type === 'contract') return node.title ?? node.contractId ?? node.id;
+  return node.path ?? node.command ?? node.name ?? node.target ?? node.id;
+}
+
+function adjacencyFor(nodes, edges) {
+  const adjacency = new Map(nodes.map((node) => [node.id, new Set()]));
+  for (const edge of edges) {
+    adjacency.get(edge.source)?.add(edge.target);
+    adjacency.get(edge.target)?.add(edge.source);
+  }
+  return adjacency;
+}
+
+function rootReachability(nodes, edges, seedIds) {
+  const adjacency = adjacencyFor(nodes, edges);
+  const reachable = new Set();
+  const depthByNode = new Map();
+  const nearestRootByNode = new Map();
+  const queue = [];
+  for (const node of nodes) {
+    if (!seedIds.has(node.id)) continue;
+    reachable.add(node.id);
+    depthByNode.set(node.id, 0);
+    nearestRootByNode.set(node.id, node.id);
+    queue.push(node.id);
+  }
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const current = queue[cursor];
+    for (const neighbor of adjacency.get(current) ?? []) {
+      if (reachable.has(neighbor)) continue;
+      reachable.add(neighbor);
+      depthByNode.set(neighbor, (depthByNode.get(current) ?? 0) + 1);
+      nearestRootByNode.set(neighbor, nearestRootByNode.get(current));
+      queue.push(neighbor);
+    }
+  }
+  return { reachable, depthByNode, nearestRootByNode };
+}
+
+export function buildImpactGraphPayload(index, impact) {
+  const graph = index?.graph ?? { nodes: [], edges: [] };
+  const config = index?.memoryConfig;
+  const seedIds = new Set((impact.changedFiles ?? [impact.changed]).map((path) => `file:${path}`));
+  const impactItems = new Map((impact.related ?? []).map((item) => [item.id, item]));
+  const isAllowedNode = (node) => {
+    if (!node) return false;
+    if (node.path && resolveMemoryArea(node.path, config)?.scope === 'local') return false;
+    return true;
+  };
+  const sourceNodes = (graph.nodes ?? []).filter(isAllowedNode);
+  const indexedNodes = new Map(sourceNodes.map((node) => [node.id, node]));
+
+  const seenEdges = new Set();
+  const edges = [];
+  for (const edge of graph.edges ?? []) {
+    if (!indexedNodes.has(edge.source) || !indexedNodes.has(edge.target)) continue;
+    const key = edgeKey(edge);
+    if (seenEdges.has(key)) continue;
+    seenEdges.add(key);
+    edges.push({ source: edge.source, target: edge.target, relation: edge.relation, confidence: edge.confidence, weight: edge.weight ?? edge.relationWeight, score: edge.score, traceabilityKey: edge.traceabilityKey });
+  }
+  const { reachable, depthByNode, nearestRootByNode } = rootReachability(sourceNodes, edges, seedIds);
+  const retainedNodes = sourceNodes.filter((node) => reachable.has(node.id));
+  const retainedEdges = edges.filter((edge) => reachable.has(edge.source) && reachable.has(edge.target));
+  const nodes = retainedNodes.map((source) => {
+    const item = impactItems.get(source.id);
+    const seed = seedIds.has(source.id);
+    return {
+      id: source.id,
+      type: source.type ?? item?.type ?? 'file',
+      path: source.path ?? item?.path,
+      label: labelForNode({ ...source, ...item }),
+      seed,
+      ranked: Boolean(item),
+      depth: depthByNode.get(source.id) ?? 0,
+      nearestRoot: nearestRootByNode.get(source.id),
+      component: 0,
+      seededComponent: true,
+      impactScore: seed ? 100 : item?.impactScore ?? 0,
+      reasons: seed ? ['changed-file'] : item?.reasons ?? [],
+      scoreBreakdown: seed ? { seed: 100 } : item?.scoreBreakdown,
+      retrieval: item?.retrieval ?? source.retrieval,
+      contractId: item?.contractId ?? source.contractId,
+      title: item?.title ?? source.title,
+      sections: item?.sections ?? source.sections,
+      vectorEvidence: item?.vectorEvidence,
+    };
+  });
+
+  return {
+    changed: impact.changed,
+    changedFiles: impact.changedFiles ?? [impact.changed],
+    ranking: impact.ranking,
+    semantic: impact.semantic,
+    complete: true,
+    nodes,
+    edges: retainedEdges,
+    components: retainedNodes.length > 0 ? [{ id: 0, size: retainedNodes.length, seeded: true }] : [],
+    diagnostics: {
+      rootNodes: retainedNodes.filter((node) => seedIds.has(node.id)).length,
+      connectedNodes: retainedNodes.length,
+      disconnectedNodesOmitted: sourceNodes.length - retainedNodes.length,
+      maximumDepth: Math.max(0, ...depthByNode.values()),
+    },
+    omittedRelated: impact.omittedRelated ?? 0,
+  };
+}

package/src/graph-view/server.mjs

@@ -0,0 +1,79 @@
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildVectorImpactOverlay } from '../impact/vector-overlay.mjs';
+import { buildImpactReport } from '../impact/report.mjs';
+import { canonicalizeChangedPath } from '../impact/vector-profile.mjs';
+import { readFreshIndex } from '../index/cache.mjs';
+import { buildImpactGraphPayload } from './payload.mjs';
+
+const ASSET_ROOT = join(dirname(fileURLToPath(import.meta.url)), 'assets');
+const CONTENT_TYPES = { '.css': 'text/css; charset=utf-8', '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.map': 'application/json; charset=utf-8' };
+const VENDOR_FILES = {
+  '/vendor/sigma.js': new URL('../../node_modules/sigma/dist/sigma.min.js', import.meta.url),
+  '/vendor/graphology.js': new URL('../../node_modules/graphology/dist/graphology.umd.min.js', import.meta.url),
+  '/vendor/d3.js': new URL('../../node_modules/d3/dist/d3.min.js', import.meta.url),
+};
+
+function json(response, status, value) {
+  response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  response.end(JSON.stringify(value));
+}
+
+function asset(response, file) {
+  try {
+    const body = readFileSync(file);
+    response.writeHead(200, { 'content-type': CONTENT_TYPES[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-store' });
+    response.end(body);
+  } catch {
+    response.writeHead(404);
+    response.end('Not found');
+  }
+}
+
+export async function buildServedImpact(root, changedPaths) {
+  const normalized = [...new Set(changedPaths.map((path) => canonicalizeChangedPath(root, path)).filter(Boolean))];
+  const { status, index, metadata } = readFreshIndex(root);
+  const overlay = await buildVectorImpactOverlay(root, index, normalized);
+  const impact = buildImpactReport(index, normalized, { overlay, verboseSemantic: false, related: 40 });
+  const graph = buildImpactGraphPayload(index, impact);
+  const graphIds = new Set(graph.nodes.map((node) => node.id));
+  const explorerImpact = {
+    ...impact,
+    related: impact.related.filter((item) => graphIds.has(item.id)),
+  };
+  return { ok: status.ok, status, metadata, impact: explorerImpact, graph };
+}
+
+export async function startImpactGraphServer({ root, changed, host = '127.0.0.1', port = 0 }) {
+  let payload = await buildServedImpact(root, changed);
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url ?? '/', `http://${request.headers.host ?? host}`);
+    if (url.pathname === '/api/impact') return json(response, 200, payload);
+    if (url.pathname === '/api/reroot') {
+      const paths = url.searchParams.getAll('changed');
+      if (paths.length === 0) return json(response, 400, { ok: false, error: { code: 'MISSING_CHANGED', message: 'At least one changed path is required.' } });
+      try {
+        payload = await buildServedImpact(root, paths);
+        return json(response, 200, payload);
+      } catch (error) {
+        return json(response, 500, { ok: false, error: { code: 'GRAPH_SERVE_FAILED', message: error instanceof Error ? error.message : String(error) } });
+      }
+    }
+    if (VENDOR_FILES[url.pathname]) return asset(response, fileURLToPath(VENDOR_FILES[url.pathname]));
+    const relative = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
+    if (!['index.html', 'app.css', 'app.js'].includes(relative)) {
+      response.writeHead(404);
+      return response.end('Not found');
+    }
+    return asset(response, join(ASSET_ROOT, relative));
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  const actualPort = typeof address === 'object' && address ? address.port : port;
+  return { server, url: `http://${host}:${actualPort}`, payload };
+}

package/src/impact/report.mjs

@@ -61,7 +61,7 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
   const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
   const seeds = changedPaths.map((path) => `file:${path}`);
   const seedSet = new Set(seeds);
-  const maxRelated = Math.max(limits.related ?? 25, seeds.length);
+  const maxRelated = Math.max(limits.related ?? 25, 0);
   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'])]));
@@ -99,7 +99,8 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
     const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores, config);
     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);
+  const rankedRelated = relatedAll.filter((item) => !seedSet.has(item.id));
+  const related = selectImpactItems(rankedRelated, maxRelated, []);
   for (const item of related) {
     if (item.type === 'file') {
       const area = docsArea(item.path, config);
@@ -122,9 +123,9 @@ export function buildImpactReport(index, changedPaths, limits = {}) {
   aggregate.perSeed = normalized.map((changed) => {
     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 };
+    const report = buildCombinedImpactReport(index, [changed], { ...limits, overlay: seedOverlay, related: Math.max(limits.related ?? 25, perSeedLimit) });
+    const related = report.related.slice(0, perSeedLimit);
+    return { changed, related, omittedRelated: Math.max(0, report.related.length - related.length) + report.omittedRelated };
   });
   return aggregate;
 }
@@ -148,7 +149,7 @@ function compactImpactGroup(group = { items: [], omitted: 0 }, limit = 5) {
 }
 
 export function buildCompactImpactReport(impact, limits = {}) {
-  const relatedLimit = Math.max(limits.related ?? 10, impact.changedFiles?.length ?? 1);
+  const relatedLimit = limits.related ?? 10;
   const groupLimit = limits.groupItems ?? 5;
   const changedFiles = impact.changedFiles ?? [impact.changed];
   const seedIds = new Set(changedFiles.map((path) => `file:${path}`));

package/src/index/cache.mjs

@@ -23,7 +23,7 @@ function mergeIncrementalGraph(previousGraph, changedGraph, changedPaths) {
   if (!previousGraph) return changedGraph;
   const changedSet = new Set(changedPaths);
   const changedNodeIds = new Set(previousGraph.nodes.filter((node) => nodeOwnedByPath(node, changedSet)).map((node) => node.id));
-  for (const node of changedGraph.nodes) changedNodeIds.add(node.id);
+  for (const node of changedGraph.nodes) if (nodeOwnedByPath(node, changedSet)) changedNodeIds.add(node.id);
   const graph = { nodes: [], edges: [] };
   for (const node of previousGraph.nodes) if (!changedNodeIds.has(node.id) && !nodeOwnedByPath(node, changedSet)) addNode(graph, node.id, node.type, Object.fromEntries(Object.entries(node).filter(([key]) => key !== 'id' && key !== 'type')));
   for (const edge of previousGraph.edges) if (!changedNodeIds.has(edge.source) && !changedNodeIds.has(edge.target)) addEdge(graph, edge.source, edge.target, edge.relation, Object.fromEntries(Object.entries(edge).filter(([key]) => key !== 'source' && key !== 'target' && key !== 'relation')));

package/src/index/constants.mjs

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

package/src/validate/references.mjs

@@ -0,0 +1,132 @@
+import { statSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { findTraceabilityLinksRegion } from '../docs/traceability.mjs';
+import { resolveMemoryArea } from '../memory/config.mjs';
+
+const blank = (text) => text.replace(/[^\n\r]/g, ' ');
+const unescape = (text) => text.replace(/\\([!"#$%&'()*+,\-./:;<=>?@[\]\\^_`{|}~])/g, '$1');
+const labelKey = (text) => unescape(text).trim().replace(/\s+/g, ' ').toLowerCase();
+const escaped = (text, index) => {
+  let count = 0;
+  while (index > 0 && text[--index] === '\\') count++;
+  return count % 2 === 1;
+};
+
+function visibleContent(content) {
+  const region = findTraceabilityLinksRegion(content);
+  let text = region.status === 'present'
+    ? content.slice(0, region.start) + blank(content.slice(region.start, region.end)) + content.slice(region.end)
+    : content;
+  const tokens = /<!--[\s\S]*?(?:-->|(?![\s\S]))|^ {0,3}(`{3,}|~{3,})[^\n]*/gm;
+  let token;
+  while ((token = tokens.exec(text))) {
+    let end = tokens.lastIndex;
+    if (token[1]) {
+      const closing = new RegExp(`^ {0,3}${token[1][0]}{${token[1].length},}[ \\t]*\\r?$`, 'gm');
+      closing.lastIndex = end + 1;
+      end = closing.exec(text) ? closing.lastIndex : text.length;
+    }
+    text = text.slice(0, token.index) + blank(text.slice(token.index, end)) + text.slice(end);
+    tokens.lastIndex = end;
+  }
+  return text;
+}
+
+// Read Markdown destinations with balanced parentheses and optional angle brackets.
+function destination(text, start) {
+  let i = start;
+  while (/\s/.test(text[i] ?? '') && i < text.length) i++;
+  const begin = i;
+  if (text[i] === '<') {
+    for (++i; i < text.length; i++) {
+      if (text[i] === '>' && !escaped(text, i)) return { href: text.slice(begin + 1, i), end: i + 1 };
+      if (text[i] === '\n') return null;
+    }
+    return null;
+  }
+  let depth = 0;
+  for (; i < text.length; i++) {
+    if (escaped(text, i)) continue;
+    if (/\s/.test(text[i]) || (text[i] === ')' && depth === 0)) break;
+    if (text[i] === '(') depth++;
+    if (text[i] === ')') depth--;
+  }
+  return depth === 0 && i > begin ? { href: text.slice(begin, i), end: i } : null;
+}
+
+export function extractMemoryReferences(content) {
+  let text = visibleContent(content);
+  const references = [];
+  const code = [];
+  const lineAt = (offset) => content.slice(0, offset).split('\n').length;
+  // Mask code before link parsing so literal Markdown inside code is not a link.
+  text = text.replace(/(`+)([\s\S]*?)\1(?!`)/g, (match, ticks, value, offset) => {
+    if (escaped(text, offset)) return match;
+    code.push({ href: value.trim(), offset, end: offset + match.length, kind: 'inline-code', line: lineAt(offset) });
+    return blank(match);
+  });
+  const definitions = new Map();
+  text = text.replace(/^ {0,3}\[([^\]\n]+)\]:[ \t]*(.*)$/gm, (match, label, value) => {
+    const parsed = destination(value, 0);
+    if (parsed && !definitions.has(labelKey(label))) definitions.set(labelKey(label), parsed.href);
+    return blank(match);
+  });
+  const linkRanges = [];
+  const labels = /!?\[((?:\\.|[^\]\\\n])*)\]/g;
+  let match;
+  while ((match = labels.exec(text))) {
+    if (escaped(text, match.index) || (match[0][0] === '!' && escaped(text, match.index + 1))) continue;
+    const after = labels.lastIndex;
+    let end = after;
+    let href;
+    if (text[after] === '(') {
+      const parsed = destination(text, after + 1);
+      if (parsed) {
+        const tail = text.slice(parsed.end).match(/^\s*(?:(?:"[^"\n]*"|'[^'\n]*'|\([^\n)]*\))\s*)?\)/);
+        if (tail) { href = parsed.href; end = parsed.end + tail[0].length; }
+      }
+    } else {
+      const suffix = text.slice(after).match(/^\[([^\]\n]*)\]/);
+      const label = suffix?.[1] || match[1];
+      href = definitions.get(labelKey(label));
+      if (suffix) end += suffix[0].length;
+    }
+    if (href !== undefined) {
+      references.push({ href: unescape(href), kind: 'markdown-link', line: lineAt(match.index) });
+      linkRanges.push([match.index, end]);
+      labels.lastIndex = end;
+    }
+  }
+  for (const item of code) {
+    if (linkRanges.some(([start, end]) => item.offset >= start && item.end <= end)) continue;
+    const path = item.href.split('#')[0];
+    // Policy A: syntax-only examples are not concrete file references.
+    if ((!path.includes('/') && !/\.[\w-]+$/.test(path)) || /[\s*?<>\[\]{}]/.test(path) || path.endsWith('/')) continue;
+    references.push({ href: item.href, kind: item.kind, line: item.line });
+  }
+  return references;
+}
+
+export function sharedLocalReferences(content, root, file, config) {
+  const source = resolveMemoryArea(relative(root, file).split('\\').join('/'), config);
+  if (source?.scope !== 'shared') return [];
+  const errors = [];
+  for (const item of extractMemoryReferences(content)) {
+    if (/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(item.href)) continue;
+    let path;
+    try { path = decodeURIComponent(item.href.split(/[?#]/)[0]); } catch { continue; }
+    if (!path) continue;
+    const base = item.kind === 'markdown-link' || /^\.\.?\//.test(path) ? dirname(file) : root;
+    const target = relative(root, resolve(base, path)).split('\\').join('/');
+    if (target === '..' || target.startsWith('../')) continue;
+    if (item.kind === 'inline-code') {
+      const configuredDirectory = (config.areas ?? []).some((area) => (area.paths ?? []).some((pattern) => pattern === `${target}/**`));
+      let directory = configuredDirectory;
+      try { directory ||= statSync(resolve(root, target)).isDirectory(); } catch { /* Missing concrete paths still receive scope checks. */ }
+      if (directory) continue;
+    }
+    const area = resolveMemoryArea(target, config);
+    if (area?.scope === 'local') errors.push({ ...item, target, sourceArea: source.id, targetArea: area.id });
+  }
+  return errors;
+}

package/src/validate/run.mjs

@@ -8,6 +8,7 @@ import { DEFAULT_VALIDATION_POLICY, cloneValidationPolicy, isMarkdownSizeExclude
 import { cacheFile, collectIndexFiles, fingerprint } from '../index/files.mjs';
 import { CACHE_DIR, CACHE_VERSION } from '../index/constants.mjs';
 import { readIndex } from '../index/cache.mjs';
+import { sharedLocalReferences } from './references.mjs';
 
 export function runValidate(argv) {
   const options = { root: '.', includeLocalMemory: false, checkIndex: false, maxLines: null, maxChars: null, linkCheck: true, json: false };
@@ -147,6 +148,11 @@ export function runValidate(argv) {
   for (const [dir, files] of byDir) {
     if (files.length > 1 && !files.some((file) => basename(file) === 'README.md')) addError(dir, 'MISSING_README', 'Directory with multiple markdown files must include README.md', null, 'add a README.md in this directory that indexes the important markdown files and their purpose.');
   }
+  for (const [file, content] of fileCache) {
+    for (const item of sharedLocalReferences(content, root, file, memoryConfig)) {
+      addError(file, 'SHARED_LOCAL_MEMORY_REFERENCE', `${item.kind} from shared area "${item.sourceArea}" targets local area "${item.targetArea}": ${item.target}`, item.line, 'replace the local reference with shared durable documentation, or remove the dependency. Inline-code directory, glob, and placeholder usage examples are allowed.');
+    }
+  }
   if (options.linkCheck) {
     for (const [file, content] of fileCache) {
       const fileDir = dirname(file);