@dotdotgod/cli 0.2.1 → 0.2.3

package/README.md

@@ -1,11 +1,13 @@
 # @dotdotgod/cli
 
-[![npm version](https://img.shields.io/npm/v/@dotdotgod/cli.svg)](https://www.npmjs.com/package/@dotdotgod/cli) [![GitHub](https://img.shields.io/badge/GitHub-dotdotgod%2Fdotdotgod--kit-181717?logo=github)](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli) [![License: Elastic 2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](../../LICENSE)
+[![npm version](https://img.shields.io/npm/v/@dotdotgod/cli.svg)](https://www.npmjs.com/package/@dotdotgod/cli) [![GitHub](https://img.shields.io/badge/GitHub-dotdotgod%2Fdotdotgod--kit-181717?logo=github)](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli) [![License: Elastic 2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://github.com/dotdotgod/dotdotgod-kit/blob/main/LICENSE)
 
 Command-line tools for dotdotgod project memory.
 
 Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, load bounded context snapshots, expand project references, or ask what should be checked after a file changes.
 
+These commands implement dotdotgod's project-memory loop — init, load, plan, impact — for shells, scripts, CI, and any agent without a dedicated adapter.
+
 ## Start Here
 
 Run one command without installing globally:
@@ -34,7 +36,7 @@ dotdotgod graph impact . --changed <path> --compact
 - `init` creates `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, and local cache ignores.
 - `validate` checks the dotdotgod docs/project-memory structure, local links, traceability blocks, config validity, and optional index freshness.
 - `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.
+- `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.
 - `traceability links` checks or repairs generated Markdown traceability-link sections.
@@ -139,4 +141,4 @@ Default exclusions include dependency, generated, cache, and secret-like paths s
 
 ## Learn More
 
-See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [Context curation](../../docs/concept/CONTEXT_CURATION.md), [Context mechanics](../../docs/concept/CONTEXT_MECHANICS.md), [Memory area config](../../docs/spec/MEMORY_AREA_CONFIG.md), and [Traceability config](../../docs/spec/TRACEABILITY_CONFIG.md).
+See the [root README](https://github.com/dotdotgod/dotdotgod-kit#readme), [Context curation](https://github.com/dotdotgod/dotdotgod-kit/blob/main/docs/concept/CONTEXT_CURATION.md), [Context mechanics](https://github.com/dotdotgod/dotdotgod-kit/blob/main/docs/concept/CONTEXT_MECHANICS.md), [Memory area config](https://github.com/dotdotgod/dotdotgod-kit/blob/main/docs/spec/MEMORY_AREA_CONFIG.md), and [Traceability config](https://github.com/dotdotgod/dotdotgod-kit/blob/main/docs/spec/TRACEABILITY_CONFIG.md).

package/package.json

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

package/src/cli/usage.mjs

@@ -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

@@ -44,6 +44,10 @@ function formatConfigOutput(payload) {
   lines.push(`- validation markdown: maxLines=${payload.config.validation.markdown.maxLines}, maxChars=${payload.config.validation.markdown.maxChars}`);
   lines.push(`- validation markdown exclude: ${(payload.config.validation.markdown.exclude ?? []).join(', ') || 'none'}`);
   lines.push(`- impact ranking preset: ${payload.config.impactRanking.preset}`);
+  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/load-snapshot.mjs

@@ -1,7 +1,7 @@
 import { parseCommon } from '../cli/usage.mjs';
 import { buildCommunities } from '../graph/communities.mjs';
 import { memoryConfigSummary, readMemoryConfig } from '../memory/config.mjs';
-import { buildMemoryAreas, detectCommandGuidance } from '../load-snapshot/summary.mjs';
+import { buildMemoryAreas, buildPinnedFiles, detectCommandGuidance } from '../load-snapshot/summary.mjs';
 import { graphSummary, readFreshIndex } from '../index/cache.mjs';
 
 export function runLoadSnapshot(argv) {
@@ -10,7 +10,9 @@ export function runLoadSnapshot(argv) {
   const summary = graphSummary(index);
   const communities = buildCommunities(index, { communities: 5, items: 5 });
   const memoryAreas = buildMemoryAreas(index, { items: 4 });
-  const memoryConfig = index.memoryConfig ?? memoryConfigSummary(readMemoryConfig(options.root));
+  const resolvedConfig = readMemoryConfig(options.root);
+  const memoryConfig = index.memoryConfig ?? memoryConfigSummary(resolvedConfig);
+  const pinnedFiles = buildPinnedFiles(options.root, resolvedConfig);
   const memoryPolicy = {
     source: memoryConfig.source ?? 'default',
     sharedAreas: (memoryConfig.areas ?? []).filter((area) => area.scope === 'shared').map((area) => area.id),
@@ -18,7 +20,7 @@ export function runLoadSnapshot(argv) {
     freshAreas: (memoryConfig.areas ?? []).filter((area) => area.freshness === 'fresh').map((area) => area.id),
     staleAreas: (memoryConfig.areas ?? []).filter((area) => area.freshness === 'stale').map((area) => area.id),
   };
-  const bounds = { communities: 5, communityItems: 5, memoryAreaItems: 4, fullGraphIncluded: false, archiveBodiesIncluded: status.archiveBodiesIncluded, archiveMapIncluded: true };
+  const bounds = { communities: 5, communityItems: 5, memoryAreaItems: 4, pinnedPathItems: pinnedFiles.bounds.maxPaths, pinnedBodyItems: pinnedFiles.bounds.maxBodies, pinnedBodyChars: pinnedFiles.bounds.maxBodyChars, fullGraphIncluded: false, archiveBodiesIncluded: status.archiveBodiesIncluded, archiveMapIncluded: true };
   const quality = {
     indexedFiles: status.indexedFiles,
     currentFiles: status.currentFiles,
@@ -28,13 +30,17 @@ export function runLoadSnapshot(argv) {
     omittedCommunityItems: communities.communities.reduce((sum, community) => sum + (community.omitted ?? 0), 0),
     memoryAreas: memoryAreas.total,
     omittedMemoryAreaItems: memoryAreas.areas.reduce((sum, area) => sum + (area.omitted ?? 0), 0),
+    pinnedPaths: pinnedFiles.paths.length,
+    omittedPinnedPaths: pinnedFiles.omittedPaths,
+    pinnedBodies: pinnedFiles.bodies.length,
+    omittedPinnedBodies: pinnedFiles.omittedBodies,
     graphNodes: summary.nodes,
     graphEdges: summary.edges,
   };
   const commandGuidance = detectCommandGuidance(options.root);
-  let payload = { root: options.root, cache: status, metadata, graph: summary, memoryConfig, memoryPolicy, memoryAreas, communities, bounds, quality, commandGuidance };
+  let payload = { root: options.root, cache: status, metadata, graph: summary, memoryConfig, memoryPolicy, memoryAreas, pinnedFiles, communities, bounds, quality, commandGuidance };
   const serialized = JSON.stringify(payload);
   payload = { ...payload, quality: { ...quality, snapshotBytes: Buffer.byteLength(serialized), approxSnapshotTokens: Math.ceil(serialized.length / 4) } };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
-  else console.log(`dotdotgod load snapshot\n- cache: ${status.status}${metadata.cacheRefreshed ? ' (refreshed)' : ''}\n- indexed files: ${status.indexedFiles}\n- current files: ${status.currentFiles}\n- archive bodies included: ${status.archiveBodiesIncluded ? 'yes' : 'no'}\n- graph: ${summary.nodes} nodes, ${summary.edges} edges\n- memory areas: ${memoryAreas.areas.length}/${memoryAreas.total} shown\n- communities: ${communities.communities.length}/${communities.total} shown, ${communities.omitted} omitted`);
+  else console.log(`dotdotgod load snapshot\n- cache: ${status.status}${metadata.cacheRefreshed ? ' (refreshed)' : ''}\n- indexed files: ${status.indexedFiles}\n- current files: ${status.currentFiles}\n- archive bodies included: ${status.archiveBodiesIncluded ? 'yes' : 'no'}\n- graph: ${summary.nodes} nodes, ${summary.edges} edges\n- memory areas: ${memoryAreas.areas.length}/${memoryAreas.total} shown\n- pinned files: ${pinnedFiles.paths.length} paths (${pinnedFiles.omittedPaths} omitted), ${pinnedFiles.bodies.length} bodies (${pinnedFiles.omittedBodies} omitted)\n- communities: ${communities.communities.length}/${communities.total} shown, ${communities.omitted} omitted`);
 }

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_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneIntegrationsPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, 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, detectCommandGuidance, detectPackageManager } from './load-snapshot/summary.mjs';
-export { isReadmeIndexPath, retrievalMetadataForPath, fileNodeMetadata } from './graph/metadata.mjs';
-export { extractMarkdownGraph, extractPackageGraph, buildGraph } from './graph/extract.mjs';
+export { buildMemoryAreas, buildPinnedFiles, detectCommandGuidance, detectPackageManager } from './load-snapshot/summary.mjs';
+export { isReadmeIndexPath, retrievalMetadataForPath } from './graph/metadata.mjs';
+export { buildGraph } from './graph/extract.mjs';
 export { addDeterministicSemanticEdges } from './graph/semantic.mjs';
 export { buildIndex, writeIndex, readIndex, getStatus, runIndex, runStatus, readFreshIndex, graphSummary } from './index/cache.mjs';
 export { runValidate } from './validate/run.mjs';
-export { buildImpactReport, buildCompactImpactReport, 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;

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/report.mjs

@@ -121,7 +121,3 @@ export function buildCompactImpactReport(impact, limits = {}) {
   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;
-}

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',
@@ -21,7 +20,7 @@ const INDEX_TEXT_FILENAMES = new Set([
 ]);
 const INDEX_EXCLUDED_DIRS = new Set(['.git', CACHE_DIR, 'node_modules', 'vendor', '.venv', 'venv', 'target', 'dist', 'build', 'coverage', '.next', '.turbo', '.cache', '.pytest_cache', '__pycache__']);
 
-function isExcludedIndexDir(path) {
+export function isExcludedIndexDir(path) {
   return path.split('/').some((part) => INDEX_EXCLUDED_DIRS.has(part));
 }
 
@@ -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/load-snapshot/summary.mjs

@@ -1,6 +1,8 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { defaultMemoryConfig, memoryAreaForPath } from '../memory/config.mjs';
+import { rel } from '../common/paths.mjs';
+import { isExcludedIndexDir } from '../index/files.mjs';
+import { defaultMemoryConfig, isSecretLikePathPattern, matchPathPattern, memoryAreaForPath } from '../memory/config.mjs';
 
 export function detectPackageManager(root) {
   const packageFile = join(root, 'package.json');
@@ -48,6 +50,98 @@ export function detectCommandGuidance(root) {
   };
 }
 
+const PINNED_WALK_CAP = 200;
+
+function walkPinnedMatches(root, base, matches, cap) {
+  if (!existsSync(base)) return [];
+  const results = [];
+  const walk = (dir) => {
+    if (results.length >= cap) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (results.length >= cap) return;
+      const absolute = join(dir, entry.name);
+      const path = rel(root, absolute);
+      if (entry.isDirectory()) {
+        if (!isExcludedIndexDir(path)) walk(absolute);
+      } else if (entry.isFile() && matches(path)) results.push(path);
+    }
+  };
+  walk(base);
+  return results;
+}
+
+function expandPinnedPattern(root, pattern) {
+  if (!pattern.includes('*')) {
+    try {
+      return statSync(join(root, pattern)).isFile() ? [pattern] : [];
+    } catch {
+      return [];
+    }
+  }
+  const base = pattern.endsWith('/**') ? join(root, pattern.slice(0, -3)) : root;
+  return walkPinnedMatches(root, base, (path) => !isSecretLikePathPattern(path) && matchPathPattern(path, pattern), PINNED_WALK_CAP);
+}
+
+function readPinnedBody(root, path, maxBodyChars) {
+  if (isSecretLikePathPattern(path)) return { path, status: 'skipped', reason: 'secret-like-path' };
+  let content;
+  try {
+    content = readFileSync(join(root, path));
+  } catch {
+    return { path, status: 'missing' };
+  }
+  if (content.includes(0)) return { path, status: 'skipped', reason: 'binary' };
+  const text = content.toString('utf8');
+  const truncated = text.length > maxBodyChars;
+  return { path, status: truncated ? 'truncated' : 'present', truncated, chars: text.length, content: truncated ? text.slice(0, maxBodyChars) : text };
+}
+
+export function buildPinnedFiles(root, config = defaultMemoryConfig(), limits = {}) {
+  const policy = config.load ?? { pinnedPaths: [], pinnedBodies: [] };
+  const maxPaths = limits.paths ?? 20;
+  const maxBodies = limits.bodies ?? 5;
+  const maxBodyChars = limits.bodyChars ?? 10000;
+  const entries = new Map();
+  const addMatches = (pattern, kind) => {
+    const matches = expandPinnedPattern(root, pattern);
+    for (const path of matches.length > 0 ? matches : [pattern]) {
+      const entry = entries.get(path) ?? { path, status: matches.length > 0 ? 'present' : 'missing', pinnedBy: new Set() };
+      entry.pinnedBy.add(kind);
+      entries.set(path, entry);
+    }
+    return matches;
+  };
+  for (const pattern of policy.pinnedPaths ?? []) addMatches(pattern, 'pinnedPaths');
+  const bodyCandidates = new Set();
+  for (const pattern of policy.pinnedBodies ?? []) {
+    for (const path of addMatches(pattern, 'pinnedBodies')) bodyCandidates.add(path);
+  }
+  const allPaths = [...entries.values()].sort((a, b) => a.path.localeCompare(b.path));
+  const paths = allPaths.slice(0, maxPaths).map((entry) => ({ path: entry.path, status: entry.status, pinnedBy: [...entry.pinnedBy].sort() }));
+  const bodies = [];
+  let omittedBodies = 0;
+  for (const path of [...bodyCandidates].sort()) {
+    if (bodies.length >= maxBodies) omittedBodies += 1;
+    else bodies.push(readPinnedBody(root, path, maxBodyChars));
+  }
+  return {
+    source: config.source ?? 'default',
+    configured: { pinnedPaths: [...(policy.pinnedPaths ?? [])], pinnedBodies: [...(policy.pinnedBodies ?? [])] },
+    paths,
+    omittedPaths: allPaths.length - paths.length,
+    bodies,
+    omittedBodies,
+    bounds: { maxPaths, maxBodies, maxBodyChars },
+  };
+}
+
 export function buildMemoryAreas(index, limits = {}) {
   const graph = index?.graph ?? { nodes: [], edges: [] };
   const itemLimit = limits.items ?? 4;

package/src/memory/config.mjs

@@ -24,6 +24,16 @@ export const DEFAULT_VALIDATION_POLICY = {
 export const DEFAULT_INTEGRATIONS_POLICY = {
   trello: { syncPaths: [] },
 };
+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',
   weights: { ppr: 40, traceability: 30, memoryPolicy: 10, verification: 15, proximity: 10, semantic: 10, freshness: 5, archivePenalty: -25 },
@@ -71,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) {
@@ -170,8 +181,22 @@ export function cloneIntegrationsPolicy(policy = DEFAULT_INTEGRATIONS_POLICY) {
   return { trello: { syncPaths: [...(policy.trello?.syncPaths ?? [])] } };
 }
 
+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() };
+  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 = '') {
@@ -214,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 {
@@ -253,11 +270,33 @@ function normalizeIntegrationsPolicy(raw) {
   return cloneIntegrationsPolicy({ trello: { syncPaths: [...new Set(syncPaths)] } });
 }
 
-function isSecretLikePathPattern(value = '') {
+export function isSecretLikePathPattern(value = '') {
   const normalized = normalizePathPattern(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),
+    documentationSummary: {
+      exclude: raw.documentationSummary?.exclude === undefined
+        ? DEFAULT_LOAD_POLICY.documentationSummary.exclude
+        : normalize(raw.documentationSummary.exclude),
+    },
+  });
+}
+
 export function trelloSyncPaths(config = defaultMemoryConfig()) {
   return [...new Set(['docs/trello/**', ...((config.integrations ?? DEFAULT_INTEGRATIONS_POLICY).trello?.syncPaths ?? [])])];
 }
@@ -361,6 +400,41 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
       }
     }
   }
+  const load = data.load;
+  if (load !== undefined) {
+    if (!load || typeof load !== 'object' || Array.isArray(load)) {
+      add('LOAD_CONFIG_INVALID', 'load', 'Expected an object.');
+    } else {
+      for (const [key, code] of [['pinnedPaths', 'LOAD_CONFIG_INVALID_PINNED_PATHS'], ['pinnedBodies', 'LOAD_CONFIG_INVALID_PINNED_BODIES']]) {
+        const values = load[key];
+        if (values === undefined) continue;
+        if (!Array.isArray(values)) add(code, `load.${key}`, 'Expected an array of path strings.');
+        else {
+          if (values.some((value) => !isValidPathPattern(value) || (typeof value === 'string' && value.trim().startsWith('/')))) add(code, `load.${key}`, 'Expected repository-relative path strings using exact paths, /** subtree patterns, or **/suffix patterns.');
+          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;
   if (referenceExpansion !== undefined) {
     if (!referenceExpansion || typeof referenceExpansion !== 'object' || Array.isArray(referenceExpansion)) {
@@ -472,7 +546,9 @@ export function readMemoryConfig(root = '.') {
       const impactRanking = normalizeImpactRankingPolicy(data.impactRanking);
       const referenceExpansion = normalizeReferenceExpansionPolicy(data.referenceExpansion);
       const integrations = normalizeIntegrationsPolicy(data.integrations);
-      return configuredAreas.length > 0 ? { source: name, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, integrations, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, integrations, source: name, errors: [] };
+      const load = normalizeLoadPolicy(data.load);
+      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.` }] };
     }
@@ -505,6 +581,8 @@ export function defaultDotdotgodConfigData() {
     impactRanking: cloneImpactRankingPolicy(config.impactRanking),
     referenceExpansion: { fuzzy: { lowSignal: { add: [], remove: [] } } },
     integrations: cloneIntegrationsPolicy(config.integrations),
+    load: cloneLoadPolicy(config.load),
+    planMode: clonePlanModePolicy(config.planMode),
   };
 }
 
@@ -531,6 +609,8 @@ export function memoryConfigSummary(config) {
     impactRanking: cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY),
     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;