@dotdotgod/claude-code 0.3.9 → 0.3.11

package/mcp/cli.mjs

@@ -1345,12 +1345,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]`;
@@ -1374,6 +1380,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:
@@ -1434,7 +1441,7 @@ function parseCommon(argv) {
 
 // packages/cli/src/validate/run.mjs
 import { existsSync as existsSync10, readFileSync as readFileSync9, readdirSync as readdirSync2 } from "node:fs";
-import { basename as basename7, dirname as dirname5, extname as extname4, join as join8, resolve as resolve7 } from "node:path";
+import { basename as basename7, dirname as dirname6, extname as extname4, join as join8, resolve as resolve8 } from "node:path";
 
 // packages/cli/src/docs/traceability.mjs
 import { existsSync as existsSync5 } from "node:fs";
@@ -1533,7 +1540,8 @@ 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.sort((a, b) => b.start - a.start).reduce((next, range) => `${next.slice(0, range.start)}${next.slice(range.end)}`, content);
+  const stripped = ranges.sort((a, b) => b.start - a.start).reduce((next, range) => `${next.slice(0, range.start)}${next.slice(range.end)}`, content);
+  return stripped.replace(/(?:^[ \t]*\r?\n)*^##[ \t]+Traceability[ \t]*\r?(?:\n(?:[ \t]*\r?\n)*|$)/gm, "");
 }
 function markdownLinkPath(root, file, target) {
   const fromDir = dirname2(file);
@@ -1710,7 +1718,7 @@ import { spawnSync } from "node:child_process";
 import { basename as basename3, extname as extname2, join as join5 } from "node:path";
 
 // packages/cli/src/index/constants.mjs
-var CACHE_VERSION = 13;
+var CACHE_VERSION = 14;
 var CACHE_DIR = ".dotdotgod";
 var MANIFEST_FILE = "manifest.json";
 
@@ -2224,7 +2232,7 @@ function mergeIncrementalGraph(previousGraph, changedGraph, changedPaths) {
   if (!previousGraph) return changedGraph;
   const changedSet = new Set(changedPaths);
   const changedNodeIds = new Set(previousGraph.nodes.filter((node2) => nodeOwnedByPath(node2, changedSet)).map((node2) => node2.id));
-  for (const node2 of changedGraph.nodes) changedNodeIds.add(node2.id);
+  for (const node2 of changedGraph.nodes) if (nodeOwnedByPath(node2, changedSet)) changedNodeIds.add(node2.id);
   const graph = { nodes: [], edges: [] };
   for (const node2 of previousGraph.nodes) if (!changedNodeIds.has(node2.id) && !nodeOwnedByPath(node2, changedSet)) addNode(graph, node2.id, node2.type, Object.fromEntries(Object.entries(node2).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")));
@@ -2321,6 +2329,138 @@ function graphSummary(index) {
   return { nodes: graph.nodes.length, edges: graph.edges.length, byType, byRelation };
 }
 
+// packages/cli/src/validate/references.mjs
+import { statSync as statSync5 } from "node:fs";
+import { dirname as dirname5, relative as relative3, resolve as resolve7 } from "node:path";
+var blank = (text) => text.replace(/[^\n\r]/g, " ");
+var unescape = (text) => text.replace(/\\([!"#$%&'()*+,\-./:;<=>?@[\]\\^_`{|}~])/g, "$1");
+var labelKey = (text) => unescape(text).trim().replace(/\s+/g, " ").toLowerCase();
+var 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;
+}
+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;
+}
+function extractMemoryReferences(content) {
+  let text = visibleContent(content);
+  const references = [];
+  const code = [];
+  const lineAt = (offset) => content.slice(0, offset).split("\n").length;
+  text = text.replace(/(`+)([\s\S]*?)\1(?!`)/g, (match2, ticks, value, offset) => {
+    if (escaped(text, offset)) return match2;
+    code.push({ href: value.trim(), offset, end: offset + match2.length, kind: "inline-code", line: lineAt(offset) });
+    return blank(match2);
+  });
+  const definitions2 = /* @__PURE__ */ new Map();
+  text = text.replace(/^ {0,3}\[([^\]\n]+)\]:[ \t]*(.*)$/gm, (match2, label, value) => {
+    const parsed = destination(value, 0);
+    if (parsed && !definitions2.has(labelKey(label))) definitions2.set(labelKey(label), parsed.href);
+    return blank(match2);
+  });
+  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 = definitions2.get(labelKey(label));
+      if (suffix) end += suffix[0].length;
+    }
+    if (href !== void 0) {
+      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];
+    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;
+}
+function sharedLocalReferences(content, root, file, config) {
+  const source = resolveMemoryArea(relative3(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) ? dirname5(file) : root;
+    const target = relative3(root, resolve7(base, path)).split("\\").join("/");
+    if (target === ".." || target.startsWith("../")) continue;
+    if (item.kind === "inline-code") {
+      const configuredDirectory = (config.areas ?? []).some((area3) => (area3.paths ?? []).some((pattern) => pattern === `${target}/**`));
+      let directory = configuredDirectory;
+      try {
+        directory ||= statSync5(resolve7(root, target)).isDirectory();
+      } catch {
+      }
+      if (directory) continue;
+    }
+    const area2 = resolveMemoryArea(target, config);
+    if (area2?.scope === "local") errors.push({ ...item, target, sourceArea: source.id, targetArea: area2.id });
+  }
+  return errors;
+}
+
 // packages/cli/src/validate/run.mjs
 function runValidate(argv) {
   const options = { root: ".", includeLocalMemory: false, checkIndex: false, maxLines: null, maxChars: null, linkCheck: true, json: false };
@@ -2335,7 +2475,7 @@ function runValidate(argv) {
     else if (!arg.startsWith("-")) options.root = arg;
     else usage(`Unknown option: ${arg}`, "validate");
   }
-  const root = resolve7(options.root);
+  const root = resolve8(options.root);
   const memoryConfig = readMemoryConfig(root);
   const documentationRoot = memoryConfig.documentation?.root ?? "docs";
   const docs = join8(root, documentationRoot);
@@ -2399,7 +2539,7 @@ README.md directory indexes, clear HTTP-status filenames such as RESPONSE_200_OK
   walk(docs);
   const dirSiblingMap = /* @__PURE__ */ new Map();
   for (const f of markdownFiles) {
-    const dir = dirname5(f);
+    const dir = dirname6(f);
     if (!dirSiblingMap.has(dir)) dirSiblingMap.set(dir, []);
     dirSiblingMap.get(dir).push(basename7(f));
   }
@@ -2415,7 +2555,7 @@ README.md directory indexes, clear HTTP-status filenames such as RESPONSE_200_OK
       const fp = validationPolicy.markdown?.filename ?? {};
       const allow = fp.allow ?? [];
       if (!allow.some((p) => matchPathPattern(rootRel, p)) && (fp.warnNumberedSeries ?? true)) {
-        const siblings = dirSiblingMap.get(dirname5(file)) ?? [];
+        const siblings = dirSiblingMap.get(dirname6(file)) ?? [];
         if (isNumberedSeriesFilename(name, siblings)) {
           const heading = extractFirstHeading(content);
           const suggestion = suggestFilenameFromHeading(heading);
@@ -2457,18 +2597,23 @@ ${traceabilityExample()}`, block.line);
     }
   }
   const byDir = /* @__PURE__ */ new Map();
-  for (const file of markdownFiles) byDir.set(dirname5(file), [...byDir.get(dirname5(file)) ?? [], file]);
+  for (const file of markdownFiles) byDir.set(dirname6(file), [...byDir.get(dirname6(file)) ?? [], file]);
   for (const [dir, files] of byDir) {
     if (files.length > 1 && !files.some((file) => basename7(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 = dirname5(file);
+      const fileDir = dirname6(file);
       for (const { href, line } of extractLinks(content)) {
         const hashIndex = href.indexOf("#");
         const pathPart = hashIndex === -1 ? href : href.slice(0, hashIndex);
         const anchor = hashIndex === -1 ? "" : href.slice(hashIndex + 1);
-        const target = pathPart ? resolve7(fileDir, pathPart) : file;
+        const target = pathPart ? resolve8(fileDir, pathPart) : file;
         if (pathPart && !existsSync10(target)) {
           addError(file, "BROKEN_LINK", `Local link target does not exist: ${pathPart}`, line, "update the link target to an existing local file, create the intended file, or remove the stale link.");
           continue;
@@ -2538,8 +2683,8 @@ Prompt: ${error.prompt}` : ""}`);
 }
 
 // packages/cli/src/commands/config.mjs
-import { existsSync as existsSync11, statSync as statSync5, writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join9, resolve as resolve8 } from "node:path";
+import { existsSync as existsSync11, statSync as statSync6, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join9, resolve as resolve9 } from "node:path";
 function parseConfigOptions(argv, usageKey = "config") {
   const options = { root: ".", json: false, template: null };
   let rootSet = false;
@@ -2557,7 +2702,7 @@ function parseConfigOptions(argv, usageKey = "config") {
     } else if (!arg.startsWith("-")) usage(`Unexpected argument: ${arg}`, usageKey);
     else usage(`Unknown option: ${arg}`, usageKey);
   }
-  options.root = resolve8(options.root);
+  options.root = resolve9(options.root);
   return options;
 }
 function configInitError(options, code, message, path = null) {
@@ -2602,7 +2747,7 @@ function runConfig(argv) {
   if (isInit) {
     if (!existsSync11(options.root)) configInitError(options, "ROOT_NOT_FOUND", `Project root not found: ${options.root}`);
     try {
-      if (!statSync5(options.root).isDirectory()) configInitError(options, "ROOT_NOT_DIRECTORY", `Project root is not a directory: ${options.root}`);
+      if (!statSync6(options.root).isDirectory()) configInitError(options, "ROOT_NOT_DIRECTORY", `Project root is not a directory: ${options.root}`);
     } catch {
       configInitError(options, "ROOT_NOT_FOUND", `Project root not found: ${options.root}`);
     }
@@ -2633,11 +2778,11 @@ function runConfig(argv) {
 }
 
 // packages/cli/src/commands/query.mjs
-import { resolve as resolve9 } from "node:path";
+import { resolve as resolve10 } from "node:path";
 
 // packages/cli/src/query/chunks.mjs
 import { readFileSync as readFileSync10, readdirSync as readdirSync3 } from "node:fs";
-import { join as join10, relative as relative3 } from "node:path";
+import { join as join10, relative as relative4 } from "node:path";
 import { createHash as createHash3 } from "node:crypto";
 var MAX_CHUNK_CHARS = 1600;
 var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage", ".git", ".dotdotgod"]);
@@ -2658,7 +2803,7 @@ function collectDocumentationMarkdown(root, exclude = ["docs/plan", "docs/archiv
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
       const absolute = join10(directory, entry.name);
-      const path = relative3(root, absolute).replaceAll("\\", "/");
+      const path = relative4(root, absolute).replaceAll("\\", "/");
       if (isSecretLikePathPattern(path) || exclude.some((pattern) => matchPathPattern(path, pattern) || path === pattern || path.startsWith(`${pattern}/`))) continue;
       if (entry.isDirectory()) {
         if (!SKIPPED_DIRECTORIES.has(entry.name)) walk(absolute);
@@ -2951,7 +3096,7 @@ function parseQueryOptions(argv) {
       options.limit = value;
     } else if (arg.startsWith("-")) usage(`Unknown option: ${arg}`, "query");
     else if (!rootSet) {
-      options.root = resolve9(arg);
+      options.root = resolve10(arg);
       rootSet = true;
     } else queryParts.push(arg);
   }
@@ -3062,19 +3207,19 @@ async function runQuery(argv) {
 }
 
 // packages/cli/src/commands/embedding.mjs
-import { resolve as resolve10 } from "node:path";
+import { resolve as resolve11 } from "node:path";
 function parse(argv) {
   const [action2 = "status", ...rest] = argv;
   let root = ".";
-  let json = false;
+  let json2 = false;
   let confirm = false;
   for (const arg of rest) {
-    if (arg === "--json") json = true;
+    if (arg === "--json") json2 = true;
     else if (arg === "--confirm") confirm = true;
     else if (!arg.startsWith("-") && root === ".") root = arg;
     else usage(`Unknown embedding option: ${arg}`, `embedding ${action2}`);
   }
-  return { action: action2, root: resolve10(root), json, confirm };
+  return { action: action2, root: resolve11(root), json: json2, confirm };
 }
 function runEmbedding(argv, options = {}) {
   const parsed = parse(argv);
@@ -3094,11 +3239,11 @@ function runEmbedding(argv, options = {}) {
 }
 
 // packages/cli/src/commands/map.mjs
-import { resolve as resolve12 } from "node:path";
+import { resolve as resolve13 } from "node:path";
 
 // packages/cli/src/memory/documentation-map.mjs
-import { existsSync as existsSync14, readdirSync as readdirSync4, statSync as statSync6 } from "node:fs";
-import { join as join13, resolve as resolve11 } from "node:path";
+import { existsSync as existsSync14, readdirSync as readdirSync4, statSync as statSync7 } from "node:fs";
+import { join as join13, resolve as resolve12 } from "node:path";
 var SKIPPED_DIRECTORIES2 = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage", ".git", ".dotdotgod"]);
 function node() {
   return { directories: /* @__PURE__ */ new Map(), files: [] };
@@ -3178,10 +3323,10 @@ function discoverMarkdown(root, documentationRoot, exclude) {
   return paths.sort();
 }
 function buildDocumentationMap(projectRoot = ".", { depth = 5 } = {}) {
-  const root = resolve11(projectRoot);
+  const root = resolve12(projectRoot);
   if (!existsSync14(root)) return { ok: false, error: { code: "ROOT_NOT_FOUND", message: `Project root not found: ${root}` } };
   try {
-    if (!statSync6(root).isDirectory()) return { ok: false, error: { code: "ROOT_NOT_FOUND", message: `Project root not found: ${root}` } };
+    if (!statSync7(root).isDirectory()) return { ok: false, error: { code: "ROOT_NOT_FOUND", message: `Project root not found: ${root}` } };
   } catch {
     return { ok: false, error: { code: "ROOT_NOT_FOUND", message: `Project root not found: ${root}` } };
   }
@@ -3201,8 +3346,8 @@ function buildDocumentationMap(projectRoot = ".", { depth = 5 } = {}) {
 }
 
 // packages/cli/src/commands/map.mjs
-function fail(json, code, message) {
-  if (json) console.log(JSON.stringify({ ok: false, error: { code, message } }, null, 2));
+function fail(json2, code, message) {
+  if (json2) console.log(JSON.stringify({ ok: false, error: { code, message } }, null, 2));
   else console.error(message);
   process.exit(2);
 }
@@ -3227,7 +3372,7 @@ function parseMapOptions(argv) {
     } else if (!arg.startsWith("-")) fail(options.json, "UNEXPECTED_ARGUMENT", `Unexpected argument: ${arg}`);
     else fail(options.json, "UNKNOWN_OPTION", `Unknown option: ${arg}`);
   }
-  options.root = resolve12(options.root);
+  options.root = resolve13(options.root);
   return options;
 }
 function runMap(argv) {
@@ -3239,7 +3384,7 @@ function runMap(argv) {
 }
 
 // packages/cli/src/reference/resolve.mjs
-import { resolve as resolve14 } from "node:path";
+import { resolve as resolve15 } from "node:path";
 
 // node_modules/.pnpm/leiden-ts@0.1.0/node_modules/leiden-ts/dist/index.js
 var GraphValidationError = class extends Error {
@@ -4475,8 +4620,8 @@ function buildCommunities(index, limits = {}) {
       byCommunity.get(communityId).push(projection.durable[index2]);
     });
     const communities = [...byCommunity.entries()].map(([communityId, nodes]) => {
-      const labelKey = labelForLeidenCommunity(nodes, config);
-      const community = makeCommunity(`leiden-${communityId}`, communityLabel(labelKey));
+      const labelKey2 = labelForLeidenCommunity(nodes, config);
+      const community = makeCommunity(`leiden-${communityId}`, communityLabel(labelKey2));
       for (const node2 of nodes.sort((a, b) => a.id.localeCompare(b.id))) addCommunityDetails(community, node2, itemLimit, config);
       return community;
     });
@@ -4611,14 +4756,14 @@ function compareImpactItems(seeds) {
 
 // packages/cli/src/impact/vector-profile.mjs
 import { lstatSync, readFileSync as readFileSync13, realpathSync } from "node:fs";
-import { extname as extname5, relative as relative4, resolve as resolve13, sep } from "node:path";
+import { extname as extname5, relative as relative5, resolve as resolve14, sep } from "node:path";
 var MAX_VECTOR_PROFILE_FILE_BYTES = 64 * 1024;
 var MAX_VECTOR_PROFILE_CHARS = 4e3;
 var MAX_VECTOR_PROFILE_METADATA_ITEMS = 20;
 var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([".c", ".cc", ".cpp", ".css", ".go", ".h", ".hpp", ".html", ".java", ".js", ".json", ".jsx", ".md", ".mjs", ".py", ".rb", ".rs", ".sh", ".ts", ".tsx", ".txt", ".yaml", ".yml"]);
 var GENERATED_SEGMENTS = /* @__PURE__ */ new Set([".dotdotgod", "build", "coverage", "dist", "node_modules"]);
 function insideRoot(root, absolute) {
-  const normalizedRoot = resolve13(root);
+  const normalizedRoot = resolve14(root);
   return absolute === normalizedRoot || absolute.startsWith(`${normalizedRoot}${sep}`);
 }
 function normalizeChangedPath(path) {
@@ -4629,17 +4774,17 @@ function normalizeChangedPath(path) {
 function canonicalizeChangedPath(root, path) {
   const normalized = normalizeChangedPath(path);
   if (!normalized) return null;
-  const rootAbsolute = resolve13(root);
-  const absolute = resolve13(rootAbsolute, normalized);
+  const rootAbsolute = resolve14(root);
+  const absolute = resolve14(rootAbsolute, normalized);
   if (!insideRoot(rootAbsolute, absolute)) return normalized;
   try {
     const canonicalRoot = realpathSync(rootAbsolute);
     const canonicalAbsolute = realpathSync(absolute);
     if (!insideRoot(canonicalRoot, canonicalAbsolute)) return normalized;
-    const canonical = relative4(canonicalRoot, canonicalAbsolute).replaceAll("\\", "/");
+    const canonical = relative5(canonicalRoot, canonicalAbsolute).replaceAll("\\", "/");
     return canonical || normalized;
   } catch {
-    return relative4(rootAbsolute, absolute).replaceAll("\\", "/") || normalized;
+    return relative5(rootAbsolute, absolute).replaceAll("\\", "/") || normalized;
   }
 }
 function unsafeProfilePath(path) {
@@ -4661,11 +4806,11 @@ function graphMetadata(graph, seedId) {
 function safeTextPrefix(root, path) {
   if (unsafeProfilePath(path) || !TEXT_EXTENSIONS.has(extname5(path).toLowerCase())) return "";
   try {
-    const absolute = resolve13(root, path);
+    const absolute = resolve14(root, path);
     if (!insideRoot(root, absolute)) return "";
     const canonicalAbsolute = realpathSync(absolute);
     if (!insideRoot(realpathSync(root), canonicalAbsolute)) return "";
-    const canonicalPath = relative4(realpathSync(root), canonicalAbsolute).replaceAll("\\", "/");
+    const canonicalPath = relative5(realpathSync(root), canonicalAbsolute).replaceAll("\\", "/");
     if (canonicalPath !== path || unsafeProfilePath(canonicalPath) || !TEXT_EXTENSIONS.has(extname5(canonicalPath).toLowerCase())) return "";
     const stats = lstatSync(canonicalAbsolute);
     if (!stats.isFile() || stats.isSymbolicLink() || stats.size > MAX_VECTOR_PROFILE_FILE_BYTES) return "";
@@ -4788,7 +4933,7 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
   const nodeById = new Map(graph.nodes.map((node2) => [node2.id, node2]));
   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, /* @__PURE__ */ new Set(["changed-file"])]));
@@ -4824,7 +4969,8 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
     const scored = scoreImpactItem({ ...node2, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores, config);
     return { ...node2, reasons: reasonList, hasCuratedEvidence, ...vectorEvidence.has(id) ? { vectorEvidence: vectorEvidence.get(id) } : {}, retrieval: { ...retrieval, signals: [.../* @__PURE__ */ 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 area2 = docsArea2(item.path, config);
@@ -4846,9 +4992,9 @@ function buildImpactReport(index, changedPaths, limits = {}) {
   aggregate2.perSeed = normalized.map((changed) => {
     const seedId = `file:${changed}`;
     const seedOverlay = limits.overlay ? { ...limits.overlay, edges: (limits.overlay.edges ?? []).filter((edge) => edge.source === seedId) } : void 0;
-    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 aggregate2;
 }
@@ -4868,7 +5014,7 @@ function compactImpactGroup(group = { items: [], omitted: 0 }, limit = 5) {
   return { items, omitted: (group.omitted ?? 0) + Math.max(0, (group.items?.length ?? 0) - items.length) };
 }
 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}`));
@@ -4881,7 +5027,7 @@ function buildCompactImpactReport(impact, limits = {}) {
 }
 
 // packages/cli/src/reference/extract.mjs
-import { basename as basename8, dirname as dirname6, extname as extname6 } from "node:path";
+import { basename as basename8, dirname as dirname7, extname as extname6 } from "node:path";
 var DEFAULT_REFERENCE_LIMIT = 5;
 function extractBracketReferences(prompt = "") {
   const refs = [];
@@ -4932,7 +5078,7 @@ function aliasEntriesForPath(path = "") {
   const parts = withoutMd.split("/").filter(Boolean);
   for (let i = 0; i < parts.length; i += 1) entries.push({ alias: parts.slice(i).join("/"), kind: "path-suffix" });
   if (base === "README.md") {
-    const dir = dirname6(path).replace(/\\/g, "/");
+    const dir = dirname7(path).replace(/\\/g, "/");
     entries.push({ alias: basename8(dir), kind: "path" });
   }
   for (const alias of [path, withoutMd, base, stem]) entries.push({ alias, kind: "path" });
@@ -4986,8 +5132,8 @@ function extractFuzzyReferences(prompt = "", index = null, options = {}) {
       }
     }
     for (const { alias } of [...aliasByKey.values()].sort((a, b) => b.priority - a.priority || b.alias.length - a.alias.length)) {
-      const escaped = alias.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "[\\s_-]+");
-      const pattern = new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, "i");
+      const escaped2 = alias.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "[\\s_-]+");
+      const pattern = new RegExp(`(^|[^a-z0-9])${escaped2}([^a-z0-9]|$)`, "i");
       if (pattern.test(lower)) add(alias, "known_alias", "medium");
       if (refs.length >= (options.maxFuzzyRefs ?? 5)) break;
     }
@@ -5062,7 +5208,7 @@ function parseReferenceOptions(argv, command) {
     else filtered.push(arg);
   }
   const operands = filtered.filter((arg) => !arg.startsWith("-"));
-  return { ...options, root: resolve14(operands[0] ?? "."), json: filtered.includes("--json"), rootArgv: operands.slice(1) };
+  return { ...options, root: resolve15(operands[0] ?? "."), json: filtered.includes("--json"), rootArgv: operands.slice(1) };
 }
 function formatReferenceOutput(payload) {
   const refreshNote = payload.metadata.cacheRefreshed ? ", refreshed" : "";
@@ -5112,7 +5258,7 @@ function runExpand(argv) {
 
 // packages/cli/src/commands/traceability.mjs
 import { existsSync as existsSync15, readFileSync as readFileSync14, readdirSync as readdirSync5, writeFileSync as writeFileSync6 } from "node:fs";
-import { join as join14, resolve as resolve15 } from "node:path";
+import { join as join14, resolve as resolve16 } from "node:path";
 function collectDocsMarkdownFiles(root) {
   const docs = join14(root, "docs");
   const files = [];
@@ -5144,7 +5290,7 @@ function parseTraceabilityOptions(argv) {
   }
   if (options.check && options.write) usage("Choose only one traceability links mode: --check or --write.", "traceability links");
   options.check = options.check || !options.write;
-  options.root = resolve15(options.root);
+  options.root = resolve16(options.root);
   return options;
 }
 function runTraceability(argv) {
@@ -5183,6 +5329,187 @@ function runTraceability(argv) {
   process.exit(ok ? 0 : 1);
 }
 
+// packages/cli/src/graph-view/server.mjs
+import { createServer } from "node:http";
+import { readFileSync as readFileSync15 } from "node:fs";
+import { dirname as dirname8, extname as extname7, join as join15 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// packages/cli/src/graph-view/payload.mjs
+function edgeKey(edge) {
+  return `${edge.source}\0${edge.target}\0${edge.relation}`;
+}
+function labelForNode(node2) {
+  if (node2.type === "contract") return node2.title ?? node2.contractId ?? node2.id;
+  return node2.path ?? node2.command ?? node2.name ?? node2.target ?? node2.id;
+}
+function adjacencyFor(nodes, edges) {
+  const adjacency = new Map(nodes.map((node2) => [node2.id, /* @__PURE__ */ 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 = /* @__PURE__ */ new Set();
+  const depthByNode = /* @__PURE__ */ new Map();
+  const nearestRootByNode = /* @__PURE__ */ new Map();
+  const queue = [];
+  for (const node2 of nodes) {
+    if (!seedIds.has(node2.id)) continue;
+    reachable.add(node2.id);
+    depthByNode.set(node2.id, 0);
+    nearestRootByNode.set(node2.id, node2.id);
+    queue.push(node2.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 };
+}
+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 = (node2) => {
+    if (!node2) return false;
+    if (node2.path && resolveMemoryArea(node2.path, config)?.scope === "local") return false;
+    return true;
+  };
+  const sourceNodes = (graph.nodes ?? []).filter(isAllowedNode);
+  const indexedNodes = new Map(sourceNodes.map((node2) => [node2.id, node2]));
+  const seenEdges = /* @__PURE__ */ 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((node2) => reachable.has(node2.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((node2) => seedIds.has(node2.id)).length,
+      connectedNodes: retainedNodes.length,
+      disconnectedNodesOmitted: sourceNodes.length - retainedNodes.length,
+      maximumDepth: Math.max(0, ...depthByNode.values())
+    },
+    omittedRelated: impact.omittedRelated ?? 0
+  };
+}
+
+// packages/cli/src/graph-view/server.mjs
+var ASSET_ROOT = join15(dirname8(fileURLToPath(import.meta.url)), "assets");
+var 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" };
+var 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 = readFileSync15(file);
+    response.writeHead(200, { "content-type": CONTENT_TYPES[extname7(file)] ?? "application/octet-stream", "cache-control": "no-store" });
+    response.end(body);
+  } catch {
+    response.writeHead(404);
+    response.end("Not found");
+  }
+}
+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((node2) => node2.id));
+  const explorerImpact = {
+    ...impact,
+    related: impact.related.filter((item) => graphIds.has(item.id))
+  };
+  return { ok: status.ok, status, metadata, impact: explorerImpact, graph };
+}
+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 relative6 = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
+    if (!["index.html", "app.css", "app.js"].includes(relative6)) {
+      response.writeHead(404);
+      return response.end("Not found");
+    }
+    return asset(response, join15(ASSET_ROOT, relative6));
+  });
+  await new Promise((resolve17, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve17);
+  });
+  const address = server.address();
+  const actualPort = typeof address === "object" && address ? address.port : port;
+  return { server, url: `http://${host}:${actualPort}`, payload };
+}
+
 // packages/cli/src/impact/format.mjs
 function formatCompactImpactGroup(name, group) {
   const items = group?.items ?? [];
@@ -5290,6 +5617,8 @@ 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];
@@ -5299,19 +5628,36 @@ function parseGraphOptions(argv) {
       }
     } else if (argv[i] === "--compact") compact = true;
     else if (argv[i] === "--yml" || argv[i] === "--yaml") yml = true;
-    else filtered.push(argv[i]);
+    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;
 }
 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 || void 0, yml: options.yml || void 0, root: options.root, error: { code: "OUTPUT_MODE_CONFLICT", message }, usage: commandUsage("graph impact") }, null, 2));

package/mcp/server.mjs

@@ -23157,7 +23157,7 @@ function markdownTree(root2, maxDepth = 5) {
   walk(docs, 1);
   return output;
 }
-async function cliJson(args, cwd) {
+async function cliText(args, cwd) {
   return await new Promise((resolvePromise, reject) => {
     const child = spawn2(process.execPath, [cli, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
     const stdout = [];
@@ -23168,14 +23168,18 @@ async function cliJson(args, cwd) {
     child.once("close", (code) => {
       const out = Buffer.concat(stdout).toString("utf8");
       if (code !== 0) return reject(new Error(Buffer.concat(stderr).toString("utf8") || out || `dotdotgod exited ${code}`));
-      try {
-        resolvePromise(JSON.parse(out));
-      } catch {
-        reject(new Error(`Expected JSON from dotdotgod: ${out.slice(0, 500)}`));
-      }
+      resolvePromise(out);
     });
   });
 }
+async function cliJson(args, cwd) {
+  const out = await cliText(args, cwd);
+  try {
+    return JSON.parse(out);
+  } catch {
+    throw new Error(`Expected JSON from dotdotgod: ${out.slice(0, 500)}`);
+  }
+}
 async function projectLoad(input) {
   const root2 = resolve5(input.root || process.cwd());
   const focus = input.focus?.trim() ?? "";
@@ -23217,8 +23221,8 @@ async function projectImpact(input) {
   if (paths.length > 20) throw new Error("paths is limited to 20 entries per call");
   const args = ["graph", "impact", root2];
   for (const path of paths) args.push("--changed", path);
-  args.push("--json");
-  return await cliJson(args, root2);
+  args.push("--compact");
+  return { ok: true, summary: (await cliText(args, root2)).trim() };
 }
 async function projectInitialize(input) {
   const root2 = resolve5(input.root || process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/claude-code",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Claude Code adapter for dotdotgod project memory workflows.",
   "type": "module",
   "license": "Elastic-2.0",
@@ -25,7 +25,7 @@
   },
   "devDependencies": {
     "esbuild": "0.27.3",
-    "@dotdotgod/context": "0.3.9"
+    "@dotdotgod/context": "0.3.11"
   },
   "files": [
     ".claude-plugin",

package/skills/document-clarify/SKILL.md

@@ -10,20 +10,31 @@ version: 1.0.0
 
 ## Memory-Area Context
 
-Run `dotdotgod config <root> --json` and use the resolved `config.areas`. Match the target path against the ordered areas and use the first match. If the CLI is unavailable, continue from the target document, nearest README, and direct links.
+Use `dotdotgod config <root> --json` (or the source-checkout CLI equivalent) to obtain resolved `config.areas`; reuse current resolved settings already in context when the project/config has not changed. Normalize the target to a repository-relative path. Check areas in order, applying each area's `excludePaths` before selecting the first matching `paths` entry. Keep the matched area's relevant guidance in context rather than repeatedly injecting the entire configuration. If no area matches, use the document's purpose and repository conventions without inventing metadata.
 
 ## Goal
 
 Make project documentation easier to understand and act on while preserving established behavior, decisions, task state, historical meaning, and traceability.
 
+## Editing Checklist
+
+Adapted from [Google Technical Writing One](https://developers.google.com/tech-writing/one); these principles supplement repository policy. Apply them directly without requiring runtime web access.
+
+- **Audience:** distinguish what readers already know from what they need to learn or do. Add only evidence-backed context that closes that gap.
+- **Terminology:** use one consistent name per concept; explain unfamiliar terms and abbreviations when readers need them. Preserve exact API names and identifiers.
+- **Sentences:** use specific verbs and make responsibility clear. Prefer active voice when it helps; retain passive voice when appropriate and never invent an unknown actor. Keep one main idea per sentence while preserving conditions, exceptions, and logical relationships.
+- **Paragraphs:** focus each paragraph on one topic and make its main point clear near the beginning. Remove sentences that do not support that topic or relocate them within the approved scope.
+- **Lists and tables:** use numbered lists when order matters, bullets otherwise, and parallel phrasing for comparable items. Use tables when readers need to compare the same attributes across items, not merely to decorate prose.
+- **Language:** apply these principles idiomatically in the document's language. Do not impose English word order, a passive-voice ban, or sentence-length quotas on Korean or other languages.
+
 ## Workflow
 
-1. Confirm the target document and requested outcome. Use its matched memory-area metadata when available: `clarify` guidance first, then `description`, `label`, and `role`.
+1. Confirm the target, audience, requested outcome, and edit scope. Diagnose ambiguity, repetition, or missing information before editing; small changes need no separate diagnostic report. Use matched memory-area metadata when available: `clarify` guidance first, then `description`, `label`, and `role`.
 2. Read only the context needed to preserve meaning: the nearest README, directly linked documents, relevant query results, and targeted history when a past decision matters.
-3. Clarify purpose, next actions, terms, ownership, headings, links, and runnable examples. Keep exact commands, paths, package names, API names, requirements, and behavior claims unless verified evidence supports a change.
-4. Prefer direct affirmative statements. Use “X is not Y; it is Z” only when that contrast resolves a likely ambiguity. Remove repeated framing, indirect wording, mixed responsibilities, and background that obscures the document's job.
-5. Follow repository-local generated markers and canonical-source instructions. For dotdotgod traceability, edit the fenced `json dotdotgod` block as the canonical mapping and use `dotdotgod traceability links <root> --write` to refresh generated links.
+3. Apply criteria suited to the document: README navigation and starting points; spec conditions, behavior, and exceptions; test procedures and pass criteria; architecture boundaries, rationale, and constraints; plan ordering, dependencies, and completion criteria; archive decisions and outcomes in their historical context. Repository-specific guidance takes priority. Clarify terms, ownership, headings, links, and runnable examples. Preserve commands, paths, package/API names, requirement strength, conditions, exceptions, unresolved questions, limitations, and evidence unless verified sources support a change. Do not invent missing facts.
+4. Prefer direct affirmative statements. Remove repeated framing, indirect wording, mixed responsibilities, and irrelevant background. Remove negative or absence statements only when deleting them leaves the reader's understanding, actions, and decisions unchanged. Rewrite redundant contrasts affirmatively: “It is not automatic; the user starts it” becomes “The user starts it.” Preserve meaningful prohibitions, unsupported cases, exceptions, security constraints, and unverified status. Use “X is not Y; it is Z” when the contrast resolves a likely ambiguity. Accuracy takes priority over brevity.
+5. Keep edits within the agreed scope. Confirm scope before splitting or moving files, changing meaning, or editing additional documents outside that scope. Update the nearest README when approved structural changes affect navigation. Follow generated markers and canonical-source instructions. For dotdotgod traceability, edit the fenced `json dotdotgod` block as the canonical mapping. Inspect `dotdotgod traceability links <root> --check --json` before using `--write`; the root-wide write can change unrelated documents, so obtain approval if its affected files exceed the agreed scope. Apply ordinary reference policy: shared documents must not depend on concrete local file paths in inline code or Markdown links; inline-code directory, glob, and placeholder usage examples remain allowed. Preserve traceability's separate stricter local-target prohibition.
 6. Ask for a decision when the requested clarification would change established meaning or when current sources conflict.
-7. Run verification that matches the changed surface. Use documentation and traceability checks for ordinary docs; add generation checks, focused package tests, dry-runs, or workspace verification when shared resources or product behavior are affected.
+7. Run verification that matches the changed surface. Use documentation and traceability checks for ordinary docs; add generation checks, focused package tests, dry-runs, or workspace verification when shared resources or product behavior are affected. Report briefly: what became clearer; important meaning preserved and unresolved questions; checks run and checks not run. Do not equate shorter text with improved accuracy.
 
 When CLI-backed routing is unavailable, continue from the target document, nearest README, direct links, and repository conventions.