@dotdotgod/cli 0.2.2 → 0.2.4

package/README.md

@@ -38,7 +38,7 @@ dotdotgod graph impact . --changed <path> --compact
 - `index` builds `.dotdotgod/manifest.json` and compact graph shards from maintained project files.
 - `load-snapshot` returns a bounded first-pass project map for AI agents, including files pinned through the `load.pinnedPaths`/`load.pinnedBodies` config so context such as code conventions stays visible on every load.
 - `resolve` and `expand` map explicit or high-signal prompt references to project files.
-- `graph impact` ranks likely related specs, tests, docs, commands, and source files for a changed path.
+- `graph impact` ranks likely related specs, tests, docs, commands, and source files for one or more changed paths, with a combined ranking and per-file top five.
 - `traceability links` checks or repairs generated Markdown traceability-link sections.
 - `plan validate` validates active plan artifacts and simplified Plan Generator checkpoints before execution.
 - `plan stage create` creates an internal `.dotdotgod-plan/NN_STAGE_NAME.md` checkpoint for a simplified Plan Generator stage.
@@ -66,8 +66,8 @@ dotdotgod plan validate docs/plan/<task-slug>/README.md
 dotdotgod plan validate docs/plan/<task-slug>/README.md --stage 04
 dotdotgod plan stage create 02 docs/plan/<task-slug>/README.md
 dotdotgod graph impact . --changed <path>
-dotdotgod graph impact . --changed <path> --compact
-dotdotgod graph impact . --changed <path> --yml
+dotdotgod graph impact . --changed <path> --changed <another-path> --compact
+dotdotgod graph impact . --changed <path> --changed <another-path> --yml
 dotdotgod graph communities .
 ```
 
@@ -104,7 +104,7 @@ files:
 - packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
 ```
 
-`graph impact` needs `--changed <path>` so ranking has a seed file. Use `--compact` for short text, `--yml` or `--yaml` for compact structured agent-facing output, and `--json` for machine-readable detail.
+`graph impact` needs at least one `--changed <path>` and accepts repeated options. Multi-file output preserves input order, deduplicates repeated paths, returns a bounded combined ranking, and includes the top five non-seed results for each changed file. Use `--compact` for short text, `--yml` or `--yaml` for compact structured agent-facing output, and `--json` for machine-readable detail.
 
 The graph is built from maintained project files: Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, imports, exports, commands, tests, and deterministic routing hints.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "CLI for dotdotgod validation, project memory snapshots, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/cli/usage.mjs

@@ -81,13 +81,13 @@ Write mode:
 Checks or writes generated Markdown traceability link sections from canonical fenced json dotdotgod blocks.`;
     case 'graph':
       return `Usage:
-  dotdotgod graph impact <root> --changed <path> [--compact|--json|--yml|--yaml]
+  dotdotgod graph impact <root> --changed <path> [--changed <path> ...] [--compact|--json|--yml|--yaml]
   dotdotgod graph communities <root> [--json]`;
     case 'graph impact':
       return `Usage:
-  dotdotgod graph impact <root> --changed <path> [--compact|--json|--yml|--yaml]
+  dotdotgod graph impact <root> --changed <path> [--changed <path> ...] [--compact|--json|--yml|--yaml]
 
-Ranks nodes related to a changed file. <root> is the project root; --changed is a project-relative file path. Use --compact for a short text summary or --yml/--yaml for structured agent-facing output.`;
+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 communities':
       return `Usage:
   dotdotgod graph communities <root> [--json]`;
@@ -109,7 +109,7 @@ Ranks nodes related to a changed file. <root> is the project root; --changed is
   dotdotgod plan validate docs/plan/<task-slug>/README.md [--stage stage] [--json]
   dotdotgod plan stage create <stage> [docs/plan/<task-slug>/README.md] [--json]
   dotdotgod trello sync <root> [--dry-run]
-  dotdotgod graph impact <root> --changed <path> [--compact|--json|--yml|--yaml]
+  dotdotgod graph impact <root> --changed <path> [--changed <path> ...] [--compact|--json|--yml|--yaml]
   dotdotgod graph communities <root> [--json]`;
   }
 }
@@ -137,17 +137,15 @@ export function isVersionToken(value) {
   return VERSION_TOKENS.has(value);
 }
 
-export function readCliVersion() {
+export function printVersion() {
+  let version = 'unknown';
   try {
     const data = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
-    return typeof data.version === 'string' ? data.version : 'unknown';
+    if (typeof data.version === 'string') version = data.version;
   } catch {
-    return 'unknown';
+    // keep 'unknown'
   }
-}
-
-export function printVersion() {
-  console.log(readCliVersion());
+  console.log(version);
   process.exit(0);
 }
 

package/src/commands/config.mjs

@@ -46,6 +46,8 @@ function formatConfigOutput(payload) {
   lines.push(`- impact ranking preset: ${payload.config.impactRanking.preset}`);
   lines.push(`- load pinned paths: ${(payload.config.load?.pinnedPaths ?? []).join(', ') || 'none'}`);
   lines.push(`- load pinned bodies: ${(payload.config.load?.pinnedBodies ?? []).join(', ') || 'none'}`);
+  lines.push(`- load documentation summary exclude: ${(payload.config.load?.documentationSummary?.exclude ?? []).join(', ') || 'none'}`);
+  lines.push(`- plan mode writable paths: ${(payload.config.planMode?.writablePaths ?? []).join(', ') || 'none'}`);
   lines.push(`- trello sync paths: ${(payload.config.integrations?.trello?.syncPaths ?? []).join(', ') || 'none'}`);
   const lowSignal = payload.config.referenceExpansion?.fuzzy?.lowSignal ?? { terms: [], add: [], remove: [] };
   lines.push(`- fuzzy low-signal terms: ${(lowSignal.terms ?? []).join(', ') || 'none'} (add: ${(lowSignal.add ?? []).join(', ') || 'none'}; remove: ${(lowSignal.remove ?? []).join(', ') || 'none'})`);

package/src/commands/graph.mjs

@@ -4,16 +4,18 @@ import { graphSummary, readFreshIndex } from '../index/cache.mjs';
 import { buildCompactImpactReport, buildImpactReport } from '../impact/report.mjs';
 import { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from '../impact/format.mjs';
 
+const MAX_CHANGED_FILES = 20;
+
 export function parseGraphOptions(argv) {
   const filtered = [];
-  let changed;
+  const changed = [];
   let compact = false;
   let yml = false;
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === '--changed') {
       const next = argv[i + 1];
       if (next && !next.startsWith('-')) {
-        changed = next;
+        changed.push(next);
         i += 1;
       }
     } else if (argv[i] === '--compact') compact = true;
@@ -21,13 +23,13 @@ export function parseGraphOptions(argv) {
     else filtered.push(argv[i]);
   }
   const options = parseCommon(filtered);
-  options.changed = changed;
+  options.changed = [...new Set(changed)];
   options.compact = compact;
   options.yml = yml;
   return options;
 }
 
-export function runGraph(argv) {
+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');
@@ -39,7 +41,7 @@ export function runGraph(argv) {
     else usage(message, 'graph impact');
     process.exit(2);
   }
-  if (isImpact && !options.changed) {
+  if (isImpact && options.changed.length === 0) {
     const message = 'Missing required option: --changed <path>. Run `dotdotgod graph impact <root> --changed <path>`.';
     if (options.json) {
       console.log(JSON.stringify({ ok: false, command: 'graph impact', compact: options.compact || undefined, root: options.root, error: { code: 'MISSING_CHANGED', message }, usage: commandUsage('graph impact') }, null, 2));
@@ -51,11 +53,23 @@ export function runGraph(argv) {
     }
     usage(message, 'graph impact');
   }
+  if (isImpact && options.changed.length > MAX_CHANGED_FILES) {
+    const message = `Too many changed files: received ${options.changed.length}; maximum is ${MAX_CHANGED_FILES}.`;
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, command: 'graph impact', root: options.root, error: { code: 'TOO_MANY_CHANGED', message }, usage: commandUsage('graph impact') }, null, 2));
+      process.exit(2);
+    }
+    if (options.yml) {
+      console.log(formatYmlGraphImpactError(options, message, 'TOO_MANY_CHANGED'));
+      process.exit(2);
+    }
+    usage(message, 'graph impact');
+  }
   const { status, index, metadata } = readFreshIndex(options.root);
   const rawImpact = isImpact ? buildImpactReport(index, options.changed) : undefined;
   const impact = isImpact && (options.compact || options.yml) ? buildCompactImpactReport(rawImpact) : rawImpact;
   const payload = isImpact
-    ? { ok: status.ok, command: 'graph impact', compact: options.compact || undefined, root: options.root, status, metadata, changed: options.changed, related: impact.related, impact }
+    ? { ok: status.ok, command: 'graph impact', compact: options.compact || undefined, root: options.root, status, metadata, changed: options.changed[0], changedFiles: options.changed, related: impact.related, impact }
     : { ok: status.ok, command: 'graph communities', root: options.root, status, metadata, graph: graphSummary(index), communities: buildCommunities(index) };
   const refreshNote = metadata.cacheRefreshed ? ', refreshed' : '';
   if (options.json) console.log(JSON.stringify(payload, null, 2));

package/src/core.mjs

@@ -15,17 +15,17 @@ export { commandUsage, hasHelpToken, helpCommandFromArgs, isHelpToken, isVersion
 export { rel } from './common/paths.mjs';
 export { extractAnchors, extractFirstHeading, extractLinks, headingToAnchor, isKebabCase, isNumberedSeriesFilename, isUpperSnakeMarkdown, removeCodeBlocks, suggestFilenameFromHeading } from './docs/markdown.mjs';
 export { extractDotdotgodTraceabilityBlocks, findTraceabilityLinksRegion, isLocalRelativeTraceabilityPath, renderCompactTraceabilityBlock, stripTraceabilityLinksRegion, syncTraceabilityLinksInContent, traceabilityExample, validateTraceabilityBlock, validateTraceabilityLinksRegion, validateTraceabilityPlacement } from './docs/traceability.mjs';
-export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_INTEGRATIONS_POLICY, DEFAULT_LOAD_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneIntegrationsPolicy, cloneLoadPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, isSecretLikePathPattern, isValidPathPattern, matchPathPattern, memoryAreaForPath, memoryConfigSummary, memoryRoleForPath, normalizeLowSignalTerm, readMemoryConfig, requiresTraceability, resolveMemoryArea, retrievalPriorityForPath, trelloSyncPaths, validateMemoryConfigData } from './memory/config.mjs';
+export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_INTEGRATIONS_POLICY, DEFAULT_LOAD_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneIntegrationsPolicy, cloneLoadPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, isSecretLikePathPattern, isValidPathPattern, matchPathPattern, memoryAreaForPath, memoryConfigSummary, normalizeLowSignalTerm, readMemoryConfig, requiresTraceability, resolveMemoryArea, trelloSyncPaths, validateMemoryConfigData } from './memory/config.mjs';
 export { buildCommunities, relationWeight } from './graph/communities.mjs';
 export { addEdge, addNode, compactGraph, expandGraph, graphStats, jsonSize, shardFile, writeJson } from './graph/store.mjs';
 export { cacheFile, collectIndexFiles, fingerprint, shouldIndexPath } from './index/files.mjs';
 export { buildMemoryAreas, buildPinnedFiles, detectCommandGuidance, detectPackageManager } from './load-snapshot/summary.mjs';
-export { isReadmeIndexPath, retrievalMetadataForPath, fileNodeMetadata } from './graph/metadata.mjs';
-export { extractMarkdownGraph, extractPackageGraph, buildGraph } from './graph/extract.mjs';
+export { isReadmeIndexPath, retrievalMetadataForPath } from './graph/metadata.mjs';
+export { buildGraph } from './graph/extract.mjs';
 export { addDeterministicSemanticEdges } from './graph/semantic.mjs';
 export { buildIndex, writeIndex, readIndex, getStatus, runIndex, runStatus, readFreshIndex, graphSummary } from './index/cache.mjs';
 export { runValidate } from './validate/run.mjs';
-export { buildImpactReport, buildCompactImpactReport, neighborhood } from './impact/report.mjs';
+export { buildImpactReport, buildCompactImpactReport } from './impact/report.mjs';
 export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from './impact/format.mjs';
 export { runConfig } from './commands/config.mjs';
 export { runLoadSnapshot } from './commands/load-snapshot.mjs';
@@ -36,11 +36,11 @@ export { parseGraphOptions, runGraph } from './commands/graph.mjs';
 export { buildPlanValidationRepairPrompt, createPlanStageCheckpoint, formatPlanValidationText, PLAN_REQUIRED_HEADERS, PLAN_STAGE_DIRECTORIES, resolvePlanValidationStage, runPlan, validatePlanArtifact } from './commands/plan.mjs';
 export { planTrelloDryRun, runTrelloSync } from './trello/sync.mjs';
 export { parseTrelloMetadata, extractTrelloShortLink } from './trello/metadata.mjs';
-export { normalizeGitHubRemote, normalizeGitHubRepositoryKey, resolveGitHubFileUrl, resolveGitHubRepositoryIdentity } from './trello/github-url.mjs';
+export { normalizeGitHubRemote, resolveGitHubFileUrl, resolveGitHubRepositoryIdentity } from './trello/github-url.mjs';
 export { buildLinkedDocsData, summarizeTraceability } from './trello/summary.mjs';
 export { formatTrelloDryRunReport, formatTrelloWriteReport } from './trello/report.mjs';
 export { createTrelloClient, resolveTrelloCredentials } from './trello/client.mjs';
-export { buildLinkedDocsCustomFieldData, customFieldTextValue, DEFAULT_DOTDOTGOD_CUSTOM_FIELD_NAME, dotdotgodCustomFieldName, mergeLinkedDocsCustomFieldValue, parseLinkedDocsCustomFieldPayload, serializeLinkedDocsCustomFieldPayload } from './trello/custom-fields.mjs';
+export { customFieldTextValue, DEFAULT_DOTDOTGOD_CUSTOM_FIELD_NAME, dotdotgodCustomFieldName, mergeLinkedDocsCustomFieldValue, parseLinkedDocsCustomFieldPayload, serializeLinkedDocsCustomFieldPayload } from './trello/custom-fields.mjs';
 
 export async function runCli(argv = process.argv.slice(2)) {
   const [command = 'help', ...args] = argv;
@@ -57,7 +57,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   else if (command === 'resolve') runResolve(args);
   else if (command === 'expand') runExpand(args);
   else if (command === 'traceability') runTraceability(args);
-  else if (command === 'graph') runGraph(args);
+  else if (command === 'graph') await runGraph(args);
   else if (command === 'plan') runPlan(args);
   else if (command === 'trello') {
     const result = await Promise.resolve(runTrelloSync(args));

package/src/graph/extract.mjs

@@ -6,7 +6,7 @@ import { defaultMemoryConfig } from '../memory/config.mjs';
 import { addEdge, addNode } from './store.mjs';
 import { addMemoryAreaMembership, addPackageResource, addTraceabilityGraph, fileNodeMetadata, headingId, isReadmeIndexPath } from './metadata.mjs';
 
-export function extractMarkdownGraph(root, file, graph, config = defaultMemoryConfig()) {
+function extractMarkdownGraph(root, file, graph, config = defaultMemoryConfig()) {
   const path = rel(root, file);
   const content = readFileSync(file, 'utf8');
   const fileId = `file:${path}`;
@@ -30,7 +30,7 @@ export function extractMarkdownGraph(root, file, graph, config = defaultMemoryCo
   addTraceabilityGraph(root, fileId, content, graph, config);
 }
 
-export function extractPackageGraph(root, file, graph) {
+function extractPackageGraph(root, file, graph) {
   const path = rel(root, file);
   const fileId = `file:${path}`;
   let pkg;

package/src/graph/store.mjs

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { SEMANTIC_RELATIONS } from '../memory/config.mjs';
+import { CACHE_DIR } from '../index/constants.mjs';
 
-const CACHE_DIR = '.dotdotgod';
 const GRAPH_NODE_SHARDS = ['docs', 'packages', 'source'];
 const GRAPH_EDGE_SHARDS = ['docs-links', 'packages', 'other'];
 

package/src/impact/format.mjs

@@ -15,7 +15,8 @@ function formatCompactImpactGroup(name, group) {
 
 export function formatCompactImpactOutput(payload, impact) {
   const refreshNote = payload.metadata.cacheRefreshed ? ', refreshed' : '';
-  const lines = [`graph impact compact: ${impact.related.length} related node(s), ${impact.omittedRelated ?? 0} omitted (${payload.status.status}${refreshNote} index)`];
+  const lines = [`graph impact compact: ${impact.related.length} related node(s), ${impact.omittedRelated ?? 0} omitted (${payload.status.status}${refreshNote} index)`, `changed files: ${(impact.changedFiles ?? [impact.changed]).join(', ')}`];
+  for (const entry of impact.perSeed ?? []) lines.push(...formatCompactImpactGroup(`top for ${entry.changed}`, { items: entry.related }));
   for (const name of ['docs', 'contracts', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatCompactImpactGroup(name, impact.groups[name]));
   return lines.join('\n');
 }
@@ -58,6 +59,7 @@ export function formatYmlImpactOutput(payload, impact) {
     'impact:',
     `  ok: ${payload.ok ? 'true' : 'false'}`,
     `  changed: ${ymlScalar(payload.changed)}`,
+    `  changed_files: ${ymlList(payload.changedFiles ?? [payload.changed])}`,
     `  root: ${ymlScalar(payload.root)}`,
     '  output: "yml"',
     '  status:',
@@ -69,8 +71,16 @@ export function formatYmlImpactOutput(payload, impact) {
     `    method: ${ymlScalar(impact.ranking?.method)}`,
     `    preset: ${ymlScalar(impact.ranking?.preset)}`,
     `    config_source: ${ymlScalar(impact.ranking?.configSource)}`,
-    '  groups:',
+    '  per_seed:',
   ];
+  for (const entry of impact.perSeed ?? []) {
+    lines.push(`    - changed: ${ymlScalar(entry.changed)}`);
+    lines.push(`      omitted_related: ${entry.omittedRelated ?? 0}`);
+    lines.push('      related:');
+    if ((entry.related ?? []).length === 0) lines.push('        []');
+    else for (const item of entry.related) lines.push(...formatYmlImpactItem(item));
+  }
+  lines.push('  groups:');
   for (const name of ['docs', 'contracts', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatYmlImpactGroup(name, impact.groups[name]));
   lines.push('  recommended_actions:');
   lines.push('    - "review_related_docs"');

package/src/impact/report.mjs

@@ -11,7 +11,13 @@ function addImpactItem(group, item, limit = 10) {
   group.items.push(item);
 }
 
-function selectImpactItems(sortedItems, maxRelated, seed) {
+function normalizeChangedPaths(changedPaths) {
+  const values = Array.isArray(changedPaths) ? changedPaths : [changedPaths];
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+function selectImpactItems(sortedItems, maxRelated, seeds) {
+  const seedSet = new Set(seeds);
   const selected = [];
   const selectedIds = new Set();
   const deferred = [];
@@ -22,35 +28,36 @@ function selectImpactItems(sortedItems, maxRelated, seed) {
   const add = (item, force = false) => {
     if (selected.length >= maxRelated || selectedIds.has(item.id)) return;
     const pathKey = item.path ?? item.id;
-    if (!force && item.id !== seed && selected.length < firstPageLimit) {
+    if (!force && !seedSet.has(item.id) && selected.length < firstPageLimit) {
       if (pathKey && (firstPagePathCounts.get(pathKey) ?? 0) >= 2) return deferred.push(item);
       if (isLowActionabilityImpactItem(item) && lowActionabilityInFirstPage >= 2) return deferred.push(item);
       if (isSemanticOnlyImpactItem(item) && semanticOnlyInFirstPage >= 3) return deferred.push(item);
     }
     selected.push(item);
     selectedIds.add(item.id);
-    if (selected.length <= firstPageLimit && item.id !== seed) {
+    if (selected.length <= firstPageLimit && !seedSet.has(item.id)) {
       if (pathKey) firstPagePathCounts.set(pathKey, (firstPagePathCounts.get(pathKey) ?? 0) + 1);
       if (isLowActionabilityImpactItem(item)) lowActionabilityInFirstPage += 1;
       if (isSemanticOnlyImpactItem(item)) semanticOnlyInFirstPage += 1;
     }
   };
-  for (const item of sortedItems) if (item.id === seed) add(item, true);
-  for (const item of sortedItems) if (item.id !== seed) add(item);
+  for (const item of sortedItems) if (seedSet.has(item.id)) add(item, true);
+  for (const item of sortedItems) if (!seedSet.has(item.id)) add(item);
   for (const item of deferred) add(item, true);
   return selected;
 }
 
-export function buildImpactReport(index, changedPath, limits = {}) {
+function buildCombinedImpactReport(index, changedPaths, limits = {}) {
   const graph = index?.graph ?? { nodes: [], edges: [] };
   const config = index?.memoryConfig ? { ...defaultMemoryConfig(), ...index.memoryConfig } : defaultMemoryConfig();
   const policy = cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY);
   const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
-  const seed = `file:${changedPath}`;
-  const maxRelated = limits.related ?? 25;
+  const seeds = changedPaths.map((path) => `file:${path}`);
+  const seedSet = new Set(seeds);
+  const maxRelated = Math.max(limits.related ?? 25, seeds.length);
   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([seed]);
-  const reasons = new Map([[seed, new Set(['changed-file'])]]);
+  const relatedIds = new Set(seeds);
+  const reasons = new Map(seeds.map((seed) => [seed, new Set(['changed-file'])]));
   const addReason = (id, reason) => {
     relatedIds.add(id);
     if (!reasons.has(id)) reasons.set(id, new Set());
@@ -58,27 +65,27 @@ export function buildImpactReport(index, changedPath, limits = {}) {
   };
 
   for (const edge of graph.edges) {
-    if (edge.source === seed) addReason(edge.target, edge.relation);
-    if (edge.target === seed) addReason(edge.source, `incoming:${edge.relation}`);
+    if (seedSet.has(edge.source)) addReason(edge.target, edge.relation);
+    if (seedSet.has(edge.target)) addReason(edge.source, `incoming:${edge.relation}`);
   }
   const expansionRelations = new Set(['implemented_by', 'verified_by', 'related_doc', 'verification_command', ...SEMANTIC_RELATIONS]);
   for (const edge of graph.edges) {
     if (!expansionRelations.has(edge.relation)) continue;
-    if (relatedIds.has(edge.source) && edge.target !== seed) addReason(edge.target, edge.relation);
+    if (relatedIds.has(edge.source) && !seedSet.has(edge.target)) addReason(edge.target, edge.relation);
   }
 
-  const pprScores = buildPersonalizedPageRank(graph, seed, policy);
-  const candidatePprMax = Math.max(0, ...[...relatedIds].filter((id) => id !== seed).map((id) => pprScores.get(id) ?? 0));
+  const pprScores = buildPersonalizedPageRank(graph, seeds, policy);
+  const candidatePprMax = Math.max(0, ...[...relatedIds].filter((id) => !seedSet.has(id)).map((id) => pprScores.get(id) ?? 0));
   const relatedAll = [...relatedIds].map((id) => {
     const node = nodeById.get(id) ?? { id };
     const path = node.path ?? id.replace(/^file:/, '').replace(/^test:/, '');
     const reasonList = [...(reasons.get(id) ?? [])];
     const retrieval = node.retrieval ?? retrievalMetadataForPath(path);
     const reasonSignals = reasonList.map((reason) => `reason:${reason}`);
-    const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seed, changedPath, policy, pprScores, candidatePprMax);
+    const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores, candidatePprMax);
     return { ...node, reasons: reasonList, retrieval: { ...retrieval, signals: [...new Set([...(retrieval.signals ?? []), ...reasonSignals])] }, ...scored };
-  }).sort(compareImpactItems(seed));
-  const related = selectImpactItems(relatedAll, maxRelated, seed);
+  }).sort(compareImpactItems(seeds));
+  const related = selectImpactItems(relatedAll, maxRelated, seeds);
   for (const item of related) {
     if (item.type === 'file') {
       const area = docsArea(item.path);
@@ -91,7 +98,19 @@ export function buildImpactReport(index, changedPath, limits = {}) {
     else if (item.type === 'event') addImpactItem(groups.events, item, limits.events ?? 10);
     else if (item.type === 'package_resource') addImpactItem(groups.packageResources, item, limits.packageResources ?? 10);
   }
-  return { changed: changedPath, ranking: { method: policy.ppr.enabled === false ? 'policy-score' : 'personalized-pagerank+policy', preset: policy.preset, configSource: index?.memoryConfig?.source ?? 'default', weights: policy.weights, ppr: policy.ppr }, related, groups, omittedRelated: Math.max(0, relatedAll.length - related.length) };
+  return { changed: changedPaths[0], changedFiles: changedPaths, ranking: { method: policy.ppr.enabled === false ? 'policy-score' : 'personalized-pagerank+policy', preset: policy.preset, configSource: index?.memoryConfig?.source ?? 'default', weights: policy.weights, ppr: policy.ppr }, related, groups, omittedRelated: Math.max(0, relatedAll.length - related.length) };
+}
+
+export function buildImpactReport(index, changedPaths, limits = {}) {
+  const normalized = normalizeChangedPaths(changedPaths);
+  const aggregate = buildCombinedImpactReport(index, normalized, limits);
+  const perSeedLimit = limits.perSeed ?? 5;
+  aggregate.perSeed = normalized.map((changed) => {
+    const report = buildCombinedImpactReport(index, [changed], { ...limits, related: Math.max(limits.related ?? 25, perSeedLimit + 1) });
+    const 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 };
+  });
+  return aggregate;
 }
 
 function compactScoreBreakdown(scoreBreakdown = {}) {
@@ -113,15 +132,14 @@ function compactImpactGroup(group = { items: [], omitted: 0 }, limit = 5) {
 }
 
 export function buildCompactImpactReport(impact, limits = {}) {
-  const relatedLimit = limits.related ?? 10;
+  const relatedLimit = Math.max(limits.related ?? 10, impact.changedFiles?.length ?? 1);
   const groupLimit = limits.groupItems ?? 5;
+  const changedFiles = impact.changedFiles ?? [impact.changed];
+  const seedIds = new Set(changedFiles.map((path) => `file:${path}`));
   const related = (impact.related ?? []).slice(0, relatedLimit).map(compactImpactItem);
   const groupNames = ['files', 'docs', 'contracts', 'tests', 'commands', 'events', 'packageResources', 'symbols'];
   const groups = Object.fromEntries(groupNames.map((name) => [name, compactImpactGroup(impact.groups?.[name], groupLimit)]));
-  const top10 = (impact.related ?? []).filter((item) => item.id !== `file:${impact.changed}`).slice(0, 10);
-  return { changed: impact.changed, compact: true, ranking: { method: impact.ranking?.method, preset: impact.ranking?.preset, configSource: impact.ranking?.configSource }, related, groups, omittedRelated: (impact.omittedRelated ?? 0) + Math.max(0, (impact.related?.length ?? 0) - related.length), quality: { rawRelated: impact.related?.length ?? 0, compactRelated: related.length, semanticOnlyTop10: top10.filter((item) => isSemanticOnlyImpactItem(item)).length, curatedTop10: top10.filter((item) => hasCuratedImpactReason(item)).length, lowActionabilityTop10: top10.filter((item) => isLowActionabilityImpactItem(item)).length } };
-}
-
-export function neighborhood(index, changedPath) {
-  return buildImpactReport(index, changedPath).related;
+  const perSeed = (impact.perSeed ?? []).map((entry) => ({ changed: entry.changed, related: (entry.related ?? []).slice(0, limits.perSeed ?? 5).map(compactImpactItem), omittedRelated: entry.omittedRelated ?? 0 }));
+  const top10 = (impact.related ?? []).filter((item) => !seedIds.has(item.id)).slice(0, 10);
+  return { changed: impact.changed, changedFiles, perSeed, compact: true, ranking: { method: impact.ranking?.method, preset: impact.ranking?.preset, configSource: impact.ranking?.configSource }, related, groups, omittedRelated: (impact.omittedRelated ?? 0) + Math.max(0, (impact.related?.length ?? 0) - related.length), quality: { rawRelated: impact.related?.length ?? 0, compactRelated: related.length, semanticOnlyTop10: top10.filter((item) => isSemanticOnlyImpactItem(item)).length, curatedTop10: top10.filter((item) => hasCuratedImpactReason(item)).length, lowActionabilityTop10: top10.filter((item) => isLowActionabilityImpactItem(item)).length } };
 }

package/src/impact/scoring.mjs

@@ -33,13 +33,16 @@ function cappedTraceabilityScore(reasons, boosts, cap) {
   return clamp(Math.max(...values) + Math.min(5, Math.max(0, values.length - 1) * 2), 0, cap);
 }
 
-export function buildPersonalizedPageRank(graph, seed, policy) {
+export function buildPersonalizedPageRank(graph, seeds, policy) {
   if (policy.ppr.enabled === false) return new Map();
+  const seedList = Array.isArray(seeds) ? [...new Set(seeds)] : [seeds];
+  const seedSet = new Set(seedList);
+  const restart = seedList.length > 0 ? 1 / seedList.length : 0;
   const damping = policy.ppr.damping ?? 0.85;
   const iterations = policy.ppr.iterations ?? 20;
   const tolerance = policy.ppr.tolerance ?? 0.000001;
   const ids = new Set(graph.nodes.map((node) => node.id));
-  ids.add(seed);
+  for (const seed of seedList) ids.add(seed);
   const adjacency = new Map([...ids].map((id) => [id, []]));
   for (const edge of graph.edges) {
     const weight = policy.relationWeights[edge.relation] ?? relationWeight(edge.relation);
@@ -49,9 +52,9 @@ export function buildPersonalizedPageRank(graph, seed, policy) {
     adjacency.get(edge.source).push([edge.target, weight]);
     adjacency.get(edge.target).push([edge.source, weight]);
   }
-  let ranks = new Map([...adjacency.keys()].map((id) => [id, id === seed ? 1 : 0]));
+  let ranks = new Map([...adjacency.keys()].map((id) => [id, seedSet.has(id) ? restart : 0]));
   for (let i = 0; i < iterations; i += 1) {
-    const next = new Map([...adjacency.keys()].map((id) => [id, id === seed ? 1 - damping : 0]));
+    const next = new Map([...adjacency.keys()].map((id) => [id, seedSet.has(id) ? (1 - damping) * restart : 0]));
     for (const [id, edges] of adjacency.entries()) {
       const rank = ranks.get(id) ?? 0;
       const total = edges.reduce((sum, [, weight]) => sum + weight, 0);
@@ -65,8 +68,10 @@ export function buildPersonalizedPageRank(graph, seed, policy) {
   return ranks;
 }
 
-export function scoreImpactItem(item, seed, changedPath, policy, pprScores, maxPpr) {
-  if (item.id === seed) return { impactScore: 100, scoreBreakdown: { seed: 100, ppr: 40, traceability: 0, memoryPolicy: 0, verification: 0, proximity: 0, semantic: 0, freshness: 0, archivePenalty: 0 } };
+export function scoreImpactItem(item, seeds, changedPaths, policy, pprScores, maxPpr) {
+  const seedSet = seeds instanceof Set ? seeds : new Set(Array.isArray(seeds) ? seeds : [seeds]);
+  const paths = Array.isArray(changedPaths) ? changedPaths : [changedPaths];
+  if (seedSet.has(item.id)) return { impactScore: 100, scoreBreakdown: { seed: 100, ppr: 40, traceability: 0, memoryPolicy: 0, verification: 0, proximity: 0, semantic: 0, freshness: 0, archivePenalty: 0 } };
   const reasons = item.reasons ?? [];
   const retrieval = item.retrieval ?? {};
   const pprNormalized = maxPpr > 0 ? (pprScores.get(item.id) ?? 0) / maxPpr : 0;
@@ -78,7 +83,7 @@ export function scoreImpactItem(item, seed, changedPath, policy, pprScores, maxP
   const semantic = clamp(sumReasonBoosts(reasons, policy.semanticBoosts), 0, Math.abs(policy.weights.semantic ?? 10));
   const freshness = retrieval.freshness === 'fresh' ? Math.abs(policy.weights.freshness ?? 5) : retrieval.freshness === 'stale' ? -Math.abs(policy.weights.freshness ?? 5) : 0;
   let archivePenalty = 0;
-  if (!changedPath.startsWith('docs/archive/')) {
+  if (!paths.some((path) => path.startsWith('docs/archive/'))) {
     if (retrieval.area === 'archive-body') archivePenalty -= Math.abs(policy.weights.archivePenalty ?? -25);
     if (retrieval.includeBodiesByDefault === false) archivePenalty -= 10;
     if (retrieval.freshness === 'stale' && retrieval.area !== 'archive-map') archivePenalty -= 5;
@@ -125,10 +130,17 @@ function impactSelectionScore(item) {
   return score;
 }
 
-export function compareImpactItems(seed) {
+export function compareImpactItems(seeds) {
+  const seedList = Array.isArray(seeds) ? seeds : [seeds];
+  const seedOrder = new Map(seedList.map((seed, index) => [seed, index]));
   return (a, b) => {
-    if (a.id === seed) return -1;
-    if (b.id === seed) return 1;
+    const aSeed = seedOrder.get(a.id);
+    const bSeed = seedOrder.get(b.id);
+    if (aSeed !== undefined || bSeed !== undefined) {
+      if (aSeed === undefined) return 1;
+      if (bSeed === undefined) return -1;
+      return aSeed - bSeed;
+    }
     return impactSelectionScore(b) - impactSelectionScore(a) || (b.impactScore ?? 0) - (a.impactScore ?? 0) || a.id.localeCompare(b.id);
   };
 }

package/src/index/files.mjs

@@ -4,9 +4,8 @@ import { spawnSync } from 'node:child_process';
 import { basename, extname, join } from 'node:path';
 import { rel } from '../common/paths.mjs';
 import { defaultMemoryConfig, readMemoryConfig, resolveMemoryArea } from '../memory/config.mjs';
+import { CACHE_DIR, MANIFEST_FILE } from './constants.mjs';
 
-const CACHE_DIR = '.dotdotgod';
-const MANIFEST_FILE = 'manifest.json';
 const INDEX_TEXT_EXTENSIONS = new Set([
   '.md', '.mdx', '.markdown', '.txt', '.rst', '.adoc', '.org',
   '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.py', '.pyw', '.go', '.rs', '.java', '.kt', '.kts', '.swift', '.rb', '.php', '.cs', '.cpp', '.cc', '.cxx', '.c', '.h', '.hpp', '.m', '.mm', '.scala', '.clj', '.cljs', '.ex', '.exs', '.erl', '.hrl', '.lua', '.pl', '.pm', '.r', '.R', '.sql',
@@ -71,25 +70,38 @@ function walkIndexCandidates(root, config = readMemoryConfig(root)) {
   return files;
 }
 
-function addDotdotgodLocalMemoryCandidates(root, candidates) {
-  for (const file of ['AGENTS.md', 'CLAUDE.md', 'CODEX.md', 'README.md', 'docs/README.md', 'docs/spec/README.md', 'docs/test/README.md', 'docs/arch/README.md', 'docs/plan/README.md', 'docs/archive/README.md']) {
-    if (existsSync(join(root, file))) candidates.add(file);
-  }
-  const planRoot = join(root, 'docs/plan');
-  const walkPlan = (dir) => {
-    if (!existsSync(dir)) return;
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const path = join(dir, entry.name);
-      if (entry.isDirectory()) walkPlan(path);
-      else if (entry.isFile()) candidates.add(rel(root, path));
+function addConfiguredLocalMemoryCandidates(root, candidates, config, limit = 5000) {
+  let added = 0;
+  const addPath = (path) => {
+    if (added >= limit || !existsSync(path)) return;
+    let stat;
+    try { stat = statSync(path); } catch { return; }
+    const pathRel = rel(root, path);
+    if (stat.isFile()) {
+      candidates.add(pathRel);
+      added += 1;
+      return;
+    }
+    if (!stat.isDirectory() || isExcludedIndexDir(pathRel)) return;
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      if (added >= limit) return;
+      addPath(join(path, entry.name));
     }
   };
-  walkPlan(planRoot);
+
+  for (const area of config.areas ?? []) {
+    if (area.scope !== 'local' || area.includeBodiesByDefault === false) continue;
+    for (const pattern of area.paths ?? []) {
+      if (pattern.startsWith('**/')) continue;
+      const base = pattern.endsWith('/**') ? pattern.slice(0, -3) : pattern;
+      addPath(join(root, base));
+    }
+  }
 }
 
 export function collectIndexFiles(root, config = readMemoryConfig(root)) {
   const candidates = new Set(gitIndexCandidates(root) ?? walkIndexCandidates(root, config));
-  addDotdotgodLocalMemoryCandidates(root, candidates);
+  addConfiguredLocalMemoryCandidates(root, candidates, config);
   return [...candidates].filter((path) => shouldIndexPath(path, config)).map((path) => join(root, path)).filter(existsSync).sort();
 }
 

package/src/init.mjs

@@ -1,10 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 
-function utcTimestamp() {
-  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
-}
-
 function action(status, path, extra = {}) {
   return { status, path, ...extra };
 }
@@ -16,10 +12,6 @@ function formatAction(item) {
   return `${item.status.padEnd(13)} ${item.path}${extras.length > 0 ? ` ${extras.join(' ')}` : ''}`;
 }
 
-function normalizeRoot(root) {
-  return resolve(root);
-}
-
 function parseInitOptions(argv) {
   const options = { root: null, projectName: '', dotdotSetting: false, force: false, dryRun: false, json: false };
   for (let i = 0; i < argv.length; i += 1) {
@@ -42,7 +34,7 @@ function parseInitOptions(argv) {
     }
   }
   if (!options.root) throw new Error('Missing required argument: <root>');
-  options.root = normalizeRoot(options.root);
+  options.root = resolve(options.root);
   if (!options.projectName) options.projectName = basename(options.root);
   return options;
 }
@@ -65,7 +57,7 @@ function writeInitFile(options, relativePath, content, actions) {
 
   let backup = '';
   if (existsSync(target) && options.force) {
-    backup = `${target}.bak.${utcTimestamp()}`;
+    backup = `${target}.bak.${new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z')}`;
     if (!options.dryRun) renameSync(target, backup);
   }
 

package/src/memory/config.mjs

@@ -27,6 +27,12 @@ export const DEFAULT_INTEGRATIONS_POLICY = {
 export const DEFAULT_LOAD_POLICY = {
   pinnedPaths: [],
   pinnedBodies: [],
+  documentationSummary: {
+    exclude: ['docs/plan', 'docs/archive'],
+  },
+};
+export const DEFAULT_PLAN_MODE_POLICY = {
+  writablePaths: ['docs/plan/**', 'docs/archive/**'],
 };
 export const DEFAULT_IMPACT_RANKING_POLICY = {
   preset: 'balanced',
@@ -75,6 +81,7 @@ const DEFAULT_MEMORY_AREAS = [
   { id: 'active-plan', label: 'Active Plans', paths: ['docs/plan/**'], scope: 'local', freshness: 'fresh', role: 'active-task-intent', priority: 95, includeBodiesByDefault: true },
   { id: 'archive-map', label: 'Archive Map', paths: ['docs/archive/README.md'], scope: 'local', freshness: 'stale', role: 'historical-memory-map', priority: 65, includeBodiesByDefault: true },
   { id: 'archive-body', label: 'Archive Body', paths: ['docs/archive/**'], excludePaths: ['docs/archive/README.md'], scope: 'local', freshness: 'stale', role: 'historical-memory-body', priority: 20, includeBodiesByDefault: false },
+  { id: 'docs', label: 'Project Documentation', paths: ['docs/**'], scope: 'shared', freshness: 'fresh', role: 'project-documentation', priority: 60, includeBodiesByDefault: true },
 ];
 
 function cloneClarifyGuidance(clarify) {
@@ -178,11 +185,18 @@ export function cloneLoadPolicy(policy = DEFAULT_LOAD_POLICY) {
   return {
     pinnedPaths: [...(policy.pinnedPaths ?? [])],
     pinnedBodies: [...(policy.pinnedBodies ?? [])],
+    documentationSummary: {
+      exclude: [...(policy.documentationSummary?.exclude ?? DEFAULT_LOAD_POLICY.documentationSummary.exclude)],
+    },
   };
 }
 
+export function clonePlanModePolicy(policy = DEFAULT_PLAN_MODE_POLICY) {
+  return { writablePaths: [...(policy.writablePaths ?? DEFAULT_PLAN_MODE_POLICY.writablePaths)] };
+}
+
 export function defaultMemoryConfig() {
-  return { source: 'default', areas: DEFAULT_MEMORY_AREAS.map(cloneArea), traceability: cloneTraceabilityPolicy(), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy(), integrations: cloneIntegrationsPolicy(), load: cloneLoadPolicy() };
+  return { source: 'default', areas: DEFAULT_MEMORY_AREAS.map(cloneArea), traceability: cloneTraceabilityPolicy(), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy(), integrations: cloneIntegrationsPolicy(), load: cloneLoadPolicy(), planMode: clonePlanModePolicy() };
 }
 
 export function normalizePathPattern(value = '') {
@@ -225,14 +239,6 @@ export function memoryAreaForPath(path = '', config = defaultMemoryConfig()) {
   return resolveMemoryArea(path, config)?.id;
 }
 
-export function memoryRoleForPath(path = '', config = defaultMemoryConfig()) {
-  return resolveMemoryArea(path, config)?.role;
-}
-
-export function retrievalPriorityForPath(path = '', config = defaultMemoryConfig()) {
-  return resolveMemoryArea(path, config)?.priority ?? 30;
-}
-
 function normalizeTraceabilityPolicy(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return cloneTraceabilityPolicy();
   return {
@@ -269,10 +275,26 @@ export function isSecretLikePathPattern(value = '') {
   return /(^|\/)(\.env|\.npmrc|\.pypirc|id_rsa|id_dsa|id_ed25519|credentials?|secrets?)(\.|\/|$)/i.test(normalized);
 }
 
+function normalizePlanModePolicy(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return clonePlanModePolicy();
+  const writablePaths = raw.writablePaths === undefined
+    ? DEFAULT_PLAN_MODE_POLICY.writablePaths
+    : [...new Set((Array.isArray(raw.writablePaths) ? raw.writablePaths : []).map(normalizePathPattern))];
+  return clonePlanModePolicy({ writablePaths });
+}
+
 function normalizeLoadPolicy(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return cloneLoadPolicy();
   const normalize = (values) => (Array.isArray(values) ? [...new Set(values.map(normalizePathPattern))] : []);
-  return cloneLoadPolicy({ pinnedPaths: normalize(raw.pinnedPaths), pinnedBodies: normalize(raw.pinnedBodies) });
+  return cloneLoadPolicy({
+    pinnedPaths: normalize(raw.pinnedPaths),
+    pinnedBodies: normalize(raw.pinnedBodies),
+    documentationSummary: {
+      exclude: raw.documentationSummary?.exclude === undefined
+        ? DEFAULT_LOAD_POLICY.documentationSummary.exclude
+        : normalize(raw.documentationSummary.exclude),
+    },
+  });
 }
 
 export function trelloSyncPaths(config = defaultMemoryConfig()) {
@@ -392,6 +414,25 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
           if (values.some((value) => typeof value === 'string' && isSecretLikePathPattern(value))) add('LOAD_CONFIG_SECRET_PINNED_PATH', `load.${key}`, 'Pinned load paths must not target secrets, credentials, environment files, or private keys.');
         }
       }
+      if (load.documentationSummary !== undefined) {
+        const summary = load.documentationSummary;
+        if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+          add('LOAD_CONFIG_INVALID_DOCUMENTATION_SUMMARY', 'load.documentationSummary', 'Expected an object.');
+        } else if (summary.exclude !== undefined) {
+          if (!Array.isArray(summary.exclude)) add('LOAD_CONFIG_INVALID_DOCUMENTATION_SUMMARY_EXCLUDE', 'load.documentationSummary.exclude', 'Expected an array of path strings.');
+          else if (summary.exclude.some((value) => !isValidPathPattern(value) || (typeof value === 'string' && value.trim().startsWith('/')))) add('LOAD_CONFIG_INVALID_DOCUMENTATION_SUMMARY_EXCLUDE', 'load.documentationSummary.exclude', 'Expected repository-relative path strings using exact paths, /** subtree patterns, or **/suffix patterns.');
+        }
+      }
+    }
+  }
+  const planMode = data.planMode;
+  if (planMode !== undefined) {
+    if (!planMode || typeof planMode !== 'object' || Array.isArray(planMode)) {
+      add('PLAN_MODE_CONFIG_INVALID', 'planMode', 'Expected an object.');
+    } else if (planMode.writablePaths !== undefined) {
+      const paths = planMode.writablePaths;
+      if (!Array.isArray(paths)) add('PLAN_MODE_CONFIG_INVALID_WRITABLE_PATHS', 'planMode.writablePaths', 'Expected an array of documentation path strings.');
+      else if (paths.some((value) => !isValidPathPattern(value) || typeof value !== 'string' || value.trim().startsWith('/') || (!normalizePathPattern(value).startsWith('docs/') && normalizePathPattern(value) !== 'docs') || normalizePathPattern(value).startsWith('docs/.') || isSecretLikePathPattern(value))) add('PLAN_MODE_CONFIG_INVALID_WRITABLE_PATHS', 'planMode.writablePaths', 'Expected safe repository-relative paths under docs/ using exact paths or /** subtree patterns.');
     }
   }
   const referenceExpansion = data.referenceExpansion;
@@ -506,7 +547,8 @@ export function readMemoryConfig(root = '.') {
       const referenceExpansion = normalizeReferenceExpansionPolicy(data.referenceExpansion);
       const integrations = normalizeIntegrationsPolicy(data.integrations);
       const load = normalizeLoadPolicy(data.load);
-      return configuredAreas.length > 0 ? { source: name, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, integrations, load, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, integrations, load, source: name, errors: [] };
+      const planMode = normalizePlanModePolicy(data.planMode);
+      return configuredAreas.length > 0 ? { source: name, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, source: name, errors: [] };
     } catch (error) {
       return { ...defaultMemoryConfig(), source: name, errors: [{ file: name, code: 'MEMORY_CONFIG_INVALID_JSON', message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}\nFix: repair ${name} so it is valid JSON, or regenerate the default config with \`dotdotgod config init <root> --force\` if you want to reset it.` }] };
     }
@@ -540,6 +582,7 @@ export function defaultDotdotgodConfigData() {
     referenceExpansion: { fuzzy: { lowSignal: { add: [], remove: [] } } },
     integrations: cloneIntegrationsPolicy(config.integrations),
     load: cloneLoadPolicy(config.load),
+    planMode: clonePlanModePolicy(config.planMode),
   };
 }
 
@@ -567,6 +610,7 @@ export function memoryConfigSummary(config) {
     referenceExpansion: cloneReferenceExpansionPolicy(config.referenceExpansion),
     integrations: cloneIntegrationsPolicy(config.integrations),
     load: cloneLoadPolicy(config.load),
+    planMode: clonePlanModePolicy(config.planMode),
   };
 }
 

package/src/reference/resolve.mjs

@@ -5,10 +5,6 @@ import { readFreshIndex } from '../index/cache.mjs';
 import { buildCompactImpactReport, buildImpactReport } from '../impact/report.mjs';
 import { DEFAULT_REFERENCE_LIMIT, extractBracketReferences, extractFuzzyReferences, isArchiveBodyPath, normalizeReferenceAlias, referenceCandidateAliases, referencePathForNode } from './extract.mjs';
 
-function incomingRouteBonus(graph, nodeId) {
-  return graph.edges.some((edge) => edge.target === nodeId && edge.relation === 'routes_to') ? 6 : 0;
-}
-
 function exactReferenceScore(ref, alias, kind) {
   const rawRef = String(ref).trim().replace(/^\[\[/, '').replace(/\]\]$/, '').split('|')[0].trim().replace(/\\/g, '/').replace(/^\.\//, '');
   const rawAlias = String(alias).trim().replace(/\\/g, '/').replace(/^\.\//, '');
@@ -40,7 +36,7 @@ export function resolveReferenceCandidates(index, ref, options = {}) {
     }
     if (!best) continue;
     const retrievalPriority = Number(node.retrievalPriority ?? node.retrieval?.priority ?? 30);
-    const routeBonus = incomingRouteBonus(graph, node.id);
+    const routeBonus = graph.edges.some((edge) => edge.target === node.id && edge.relation === 'routes_to') ? 6 : 0;
     const memoryBonus = Math.min(12, Math.max(0, retrievalPriority / 10));
     const headingBonus = node.type === 'heading' ? 2 : 0;
     const score = Number((best.score + routeBonus + memoryBonus + headingBonus).toFixed(1));
@@ -80,13 +76,6 @@ function parseReferenceOptions(argv, command) {
   return { ...options, root: resolve(operands[0] ?? '.'), json: filtered.includes('--json'), rootArgv: operands.slice(1) };
 }
 
-function attachImpactToRef(index, refResult) {
-  const topPath = refResult.top?.path;
-  if (!topPath) return refResult;
-  const impact = buildCompactImpactReport(buildImpactReport(index, topPath));
-  return { ...refResult, impact: { changed: topPath, related: impact.related, groups: impact.groups, omittedRelated: impact.omittedRelated, quality: impact.quality } };
-}
-
 function formatReferenceOutput(payload) {
   const refreshNote = payload.metadata.cacheRefreshed ? ', refreshed' : '';
   const lines = [`${payload.command}: ${payload.refs.length} reference(s) (${payload.status.status}${refreshNote} index)`];
@@ -124,7 +113,12 @@ export function runExpand(argv) {
     ...refsInPrompt.map((item) => ({ ...resolveReferenceCandidates(index, item.target, options), source: 'explicit', raw: item.raw, label: item.label })),
     ...fuzzyRefs.map((item) => ({ ...resolveReferenceCandidates(index, item.target, options), source: 'fuzzy', raw: item.raw, confidence: item.confidence, reasons: item.reasons })),
   ];
-  if (options.withImpact) refs = refs.map((item) => attachImpactToRef(index, item));
+  if (options.withImpact) refs = refs.map((item) => {
+    const topPath = item.top?.path;
+    if (!topPath) return item;
+    const impact = buildCompactImpactReport(buildImpactReport(index, topPath));
+    return { ...item, impact: { changed: topPath, related: impact.related, groups: impact.groups, omittedRelated: impact.omittedRelated, quality: impact.quality } };
+  });
   const payload = { ok: status.ok, command: 'expand', root: options.root, prompt, status, metadata, refs, omitted: refs.reduce((sum, item) => sum + item.omitted, 0) };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else console.log(formatReferenceOutput(payload));

package/src/trello/custom-fields.mjs

@@ -8,7 +8,7 @@ export function dotdotgodCustomFieldName({ env = process.env, name = '' } = {})
   return cleanString(name) || cleanString(env.DOTDOTGOD_TRELLO_CUSTOM_FIELD_NAME) || DEFAULT_DOTDOTGOD_CUSTOM_FIELD_NAME;
 }
 
-export function buildLinkedDocsCustomFieldData({ docsPath, githubUrl, trelloUrl, repositoryKey, repositoryLabel, title, summary, traceabilityState, traceabilityDetails = [] } = {}) {
+function buildLinkedDocsCustomFieldData({ docsPath, githubUrl, trelloUrl, repositoryKey, repositoryLabel, title, summary, traceabilityState, traceabilityDetails = [] } = {}) {
   return {
     repositoryKey: cleanString(repositoryKey),
     repositoryLabel: cleanString(repositoryLabel) || cleanString(repositoryKey).split('/').filter(Boolean).at(-1) || '',
@@ -22,12 +22,8 @@ export function buildLinkedDocsCustomFieldData({ docsPath, githubUrl, trelloUrl,
   };
 }
 
-function normalizeEntry(entry = {}) {
-  return buildLinkedDocsCustomFieldData(entry);
-}
-
 export function serializeLinkedDocsCustomFieldPayload(entries = []) {
-  return JSON.stringify({ version: 1, entries: entries.map(normalizeEntry) });
+  return JSON.stringify({ version: 1, entries: entries.map((entry) => buildLinkedDocsCustomFieldData(entry)) });
 }
 
 export function parseLinkedDocsCustomFieldPayload(text = '') {
@@ -54,7 +50,7 @@ export function parseLinkedDocsCustomFieldPayload(text = '') {
       },
     };
   }
-  const entries = parsed.entries.map(normalizeEntry);
+  const entries = parsed.entries.map((entry) => buildLinkedDocsCustomFieldData(entry));
   const keys = entries.map((entry) => entry.repositoryKey).filter(Boolean);
   if (keys.length !== new Set(keys).size) {
     return {
@@ -69,7 +65,7 @@ export function parseLinkedDocsCustomFieldPayload(text = '') {
 }
 
 export function mergeLinkedDocsCustomFieldValue(existingText = '', entry = {}) {
-  const current = normalizeEntry(entry);
+  const current = buildLinkedDocsCustomFieldData(entry);
   if (!current.repositoryKey) {
     return {
       ok: false,

package/src/trello/github-url.mjs

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 
-export function normalizeGitHubRepositoryKey(value = '') {
+function normalizeGitHubRepositoryKey(value = '') {
   const text = String(value).trim();
   const match = text.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/u);
   if (!match) return null;