@dotdotgod/cli 0.1.29 → 0.1.35

package/README.md

@@ -31,6 +31,7 @@ Command-line tools for dotdotgod project memory. The CLI turns explicit, maintai
 
 - Initialize `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, and local cache ignores with `dotdotgod init`.
 - Replace ad-hoc docs checks with `dotdotgod validate`.
+- Keep generated Markdown traceability links synchronized with `dotdotgod traceability links`.
 - Build `.dotdotgod/` as a local ignored cache of file fingerprints and compact graph shards derived from maintained project links.
 - Use `load-snapshot` as a bounded first-pass map for high-quality agent loading.
 - Resolve explicit `[[...]]` references or high-signal fuzzy references before broad text search.
@@ -53,13 +54,26 @@ dotdotgod load-snapshot .
 dotdotgod resolve . PLAN_MODE
 dotdotgod expand . "Update [[PLAN_MODE]] and [[HOOKS]]"
 dotdotgod expand . "PLAN_MODE 수정하자" --fuzzy
+dotdotgod traceability links . --check
+dotdotgod traceability links . --write
 dotdotgod graph impact . --changed <path>
 dotdotgod graph impact . --changed <path> --compact
 dotdotgod graph impact . --changed <path> --yml
 dotdotgod graph communities .
 ```
 
-`--help`, `-h`, and `help` print usage to stdout. Command-specific help is available with `dotdotgod <command> --help`, including nested commands such as `dotdotgod graph impact --help` and `dotdotgod config init --help`.
+`--help`, `-h`, and `help` print usage to stdout. Command-specific help is available with `dotdotgod <command> --help`, including nested commands such as `dotdotgod graph impact --help`, `dotdotgod config init --help`, and `dotdotgod traceability links --help`.
+
+## Validation and Verification Boundaries
+
+| Command | Responsibility |
+| --- | --- |
+| `dotdotgod validate <root>` | Checks dotdotgod docs/project-memory structure, local links, traceability blocks, generated traceability-link drift, config validity, and optional index freshness. |
+| `dotdotgod traceability links <root> --check` | Runs only the generated traceability-link and compact JSON drift check. |
+| `dotdotgod traceability links <root> --write` | Repairs generated traceability-link sections and rewrites canonical `json dotdotgod` blocks as compact JSON. |
+| `pnpm run verify` | Runs the repository-level quality gate: generated-resource checks, package verify contracts, tests, typecheck, and docs validation where each package defines it. |
+
+Most users start with `validate`. Use `traceability links --write` only when generated traceability output needs repair, and use `verify` before release-style handoff.
 
 ## Graph, Cache, and Impact
 

package/package.json

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

package/src/cli/usage.mjs

@@ -40,6 +40,14 @@ Create dotdotgod.config.json with the built-in default memory, traceability, val
     case 'expand':
       return `Usage:
   dotdotgod expand <root> <prompt> [--max-results n] [--include-archive] [--with-impact] [--fuzzy] [--json]`;
+    case 'traceability':
+      return `Usage:
+  dotdotgod traceability links <root> [--check|--write] [--json]`;
+    case 'traceability links':
+      return `Usage:
+  dotdotgod traceability links <root> [--check|--write] [--json]
+
+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]
@@ -66,6 +74,7 @@ Ranks nodes related to a changed file. <root> is the project root; --changed is
   dotdotgod load-snapshot <root> [--json]
   dotdotgod resolve <root> <ref> [--max-results n] [--include-archive] [--json]
   dotdotgod expand <root> <prompt> [--max-results n] [--include-archive] [--with-impact] [--fuzzy] [--json]
+  dotdotgod traceability links <root> [--check|--write] [--json]
   dotdotgod graph impact <root> --changed <path> [--compact|--json|--yml|--yaml]
   dotdotgod graph communities <root> [--json]`;
   }
@@ -111,6 +120,7 @@ export function printVersion() {
 export function helpCommandFromArgs(args) {
   const nonHelp = args.filter((arg) => !isHelpToken(arg));
   if (nonHelp[0] === 'graph' && nonHelp[1]) return `graph ${nonHelp[1]}`;
+  if (nonHelp[0] === 'traceability' && nonHelp[1]) return `traceability ${nonHelp[1]}`;
   if (nonHelp[0] === 'config' && nonHelp[1] === 'init') return 'config init';
   return nonHelp[0] ?? 'root';
 }

package/src/core.mjs

@@ -6,7 +6,7 @@ import { runInit } from './init.mjs';
 import { commandUsage, hasHelpToken, helpCommandFromArgs, isHelpToken, isVersionToken, parseCommon, printVersion, usage } from './cli/usage.mjs';
 import { rel } from './common/paths.mjs';
 import { extractAnchors, extractLinks, headingToAnchor, isKebabCase, isUpperSnakeMarkdown, removeCodeBlocks } from './docs/markdown.mjs';
-import { extractDotdotgodTraceabilityBlocks, isLocalRelativeTraceabilityPath, traceabilityExample, validateTraceabilityBlock, validateTraceabilityPlacement } from './docs/traceability.mjs';
+import { extractDotdotgodTraceabilityBlocks, findTraceabilityLinksRegion, isLocalRelativeTraceabilityPath, renderCompactTraceabilityBlock, stripTraceabilityLinksRegion, syncTraceabilityLinksInContent, traceabilityExample, validateTraceabilityBlock, validateTraceabilityLinksRegion, validateTraceabilityPlacement } from './docs/traceability.mjs';
 import { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, memoryAreaForPath, memoryConfigSummary, memoryRoleForPath, normalizeLowSignalTerm, readMemoryConfig, requiresTraceability, resolveMemoryArea, retrievalPriorityForPath, validateMemoryConfigData } from './memory/config.mjs';
 import { buildCommunities, relationWeight } from './graph/communities.mjs';
 import { addEdge, addNode, compactGraph, expandGraph, graphStats, jsonSize, shardFile, writeJson } from './graph/store.mjs';
@@ -16,13 +16,13 @@ import { buildMemoryAreas, detectCommandGuidance, detectPackageManager } from '.
 export { commandUsage, hasHelpToken, helpCommandFromArgs, isHelpToken, isVersionToken, parseCommon, printVersion, usage } from './cli/usage.mjs';
 export { rel } from './common/paths.mjs';
 export { extractAnchors, extractLinks, headingToAnchor, isKebabCase, isUpperSnakeMarkdown, removeCodeBlocks } from './docs/markdown.mjs';
-export { extractDotdotgodTraceabilityBlocks, isLocalRelativeTraceabilityPath, traceabilityExample, validateTraceabilityBlock, validateTraceabilityPlacement } from './docs/traceability.mjs';
+export { extractDotdotgodTraceabilityBlocks, findTraceabilityLinksRegion, isLocalRelativeTraceabilityPath, renderCompactTraceabilityBlock, stripTraceabilityLinksRegion, syncTraceabilityLinksInContent, traceabilityExample, validateTraceabilityBlock, validateTraceabilityLinksRegion, validateTraceabilityPlacement } from './docs/traceability.mjs';
 export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, memoryAreaForPath, memoryConfigSummary, memoryRoleForPath, normalizeLowSignalTerm, readMemoryConfig, requiresTraceability, resolveMemoryArea, retrievalPriorityForPath, 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 const CACHE_VERSION = 10;
+export const CACHE_VERSION = 11;
 const CACHE_DIR = '.dotdotgod';
 const MANIFEST_FILE = 'manifest.json';
 export function runValidate(argv) {
@@ -81,18 +81,25 @@ export function runValidate(argv) {
     if (docsRel && !docsRel.startsWith('..') && !isUpperSnakeMarkdown(name)) addError(file, 'FILE_NAMING', `Markdown file must be UPPER_SNAKE_CASE.md or README.md: ${name}`, null, 'rename the markdown file to UPPER_SNAKE_CASE.md or README.md and update any links that reference it.');
     const content = readFileSync(file, 'utf8');
     fileCache.set(file, content);
-    const lines = content.split('\n').length;
+    const budgetContent = stripTraceabilityLinksRegion(content);
+    const lines = budgetContent.split('\n').length;
+    const chars = budgetContent.length;
     const path = rel(root, file);
     const skipSizeChecks = isMarkdownSizeExcluded(path, memoryConfig);
-    if (!skipSizeChecks && lines > maxLines) addError(file, 'FILE_TOO_LONG', `Markdown file has ${lines} lines; max is ${maxLines}`, null, 'split the document into focused markdown files and update the nearest README.md index, or add a narrow validation.markdown.exclude entry if this file is intentionally oversized.');
-    if (!skipSizeChecks && content.length > maxChars) addError(file, 'FILE_TOO_LARGE', `Markdown file has ${content.length} characters; max is ${maxChars}`, null, 'split the document into focused markdown files and update the nearest README.md index, or add a narrow validation.markdown.exclude entry if this file is intentionally oversized.');
+    if (!skipSizeChecks && lines > maxLines) addError(file, 'FILE_TOO_LONG', `Markdown file has ${lines} lines excluding generated traceability links and traceability JSON blocks; max is ${maxLines}`, null, 'split the document into focused markdown files and update the nearest README.md index, or add a narrow validation.markdown.exclude entry if this file is intentionally oversized.');
+    if (!skipSizeChecks && chars > maxChars) addError(file, 'FILE_TOO_LARGE', `Markdown file has ${chars} characters excluding generated traceability links and traceability JSON blocks; max is ${maxChars}`, null, 'split the document into focused markdown files and update the nearest README.md index, or add a narrow validation.markdown.exclude entry if this file is intentionally oversized.');
     if (requiresTraceability(rel(root, file), memoryConfig)) {
       const blocks = extractDotdotgodTraceabilityBlocks(content);
       if (blocks.length === 0) addError(file, 'TRACEABILITY_MISSING', `Behavior specs must include a fenced \`json dotdotgod\` traceability block as the final section.\nFix: add a final \`## Traceability\` section with the expected \`json dotdotgod\` block and point it at the relevant source, tests, related docs, and verification commands.\n\n${traceabilityExample()}`);
       else for (const error of validateTraceabilityPlacement(content, root, file)) errors.push(error);
+      for (const error of validateTraceabilityLinksRegion(content, root, file)) errors.push(error);
       for (const block of blocks) {
         if (block.error) addError(file, 'TRACEABILITY_INVALID_JSON', `Invalid \`json dotdotgod\` block: ${block.error}\nFix: repair the fenced \`json dotdotgod\` block so it is valid JSON and still matches the expected schema.\n\n${traceabilityExample()}`, block.line);
-        else for (const error of validateTraceabilityBlock(block.data, root, file, block.line)) errors.push(error);
+        else {
+          for (const error of validateTraceabilityBlock(block.data, root, file, block.line, memoryConfig)) errors.push(error);
+          const synced = syncTraceabilityLinksInContent(content, block.data, root, file);
+          if (synced.ok && synced.changed) addError(file, 'TRACEABILITY_LINKS_STALE', 'Generated traceability links or compact traceability JSON are missing or stale.', block.line, 'run `dotdotgod traceability links <root> --write` to synchronize the generated Markdown links and compact JSON block.');
+        }
       }
     }
   }
@@ -1368,6 +1375,75 @@ export function runExpand(argv) {
   else console.log(formatReferenceOutput(payload));
 }
 
+function collectDocsMarkdownFiles(root) {
+  const docs = join(root, 'docs');
+  const files = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile() && entry.name.endsWith('.md')) files.push(path);
+    }
+  };
+  walk(docs);
+  return files;
+}
+
+export function parseTraceabilityOptions(argv) {
+  const sub = argv[0];
+  const action = argv[1];
+  if (sub !== 'links') usage(sub ? `Unknown traceability command: ${sub}` : 'Missing traceability command.', 'traceability');
+  const options = { root: '.', check: false, write: false, json: false };
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--check') options.check = true;
+    else if (arg === '--write') options.write = true;
+    else if (arg === '--json') options.json = true;
+    else if (!arg.startsWith('-')) options.root = arg;
+    else usage(`Unknown option: ${arg}`, 'traceability links');
+  }
+  if (action === '--check' || action === '--write' || action === '--json') {
+    // no-op: action slot is an option, not a positional subcommand.
+  }
+  if (options.check && options.write) usage('Choose only one traceability links mode: --check or --write.', 'traceability links');
+  options.check = options.check || !options.write;
+  options.root = resolve(options.root);
+  return options;
+}
+
+export function runTraceability(argv) {
+  const options = parseTraceabilityOptions(argv);
+  const files = collectDocsMarkdownFiles(options.root);
+  const results = [];
+  const errors = [];
+  for (const file of files) {
+    const content = readFileSync(file, 'utf8');
+    for (const error of validateTraceabilityLinksRegion(content, options.root, file)) errors.push(error);
+    const blocks = extractDotdotgodTraceabilityBlocks(content).filter((block) => !block.error);
+    if (blocks.length === 0) continue;
+    const result = syncTraceabilityLinksInContent(content, blocks.at(-1).data, options.root, file);
+    if (!result.ok) {
+      for (const error of result.errors ?? []) errors.push(error);
+      continue;
+    }
+    if (options.write && result.changed) writeFileSync(file, result.content);
+    if (result.changed) results.push({ file: rel(options.root, file), changed: true });
+  }
+  const ok = errors.length === 0 && (!options.check || results.length === 0);
+  const payload = { ok, command: 'traceability links', root: options.root, mode: options.write ? 'write' : 'check', changed: results.length, files: results, errors };
+  if (options.json) console.log(JSON.stringify(payload, null, 2));
+  else if (errors.length > 0) {
+    for (const error of errors) console.log(`${error.line ? `${error.file}:${error.line}` : error.file} [${error.code}] ${error.message}`);
+    console.log(`\n❌ ${errors.length} traceability link error(s)`);
+  } else if (options.check && results.length > 0) {
+    for (const result of results) console.log(`${result.file} [TRACEABILITY_LINKS_STALE] generated traceability links are missing or stale.`);
+    console.log(`\n❌ ${results.length} traceability link file(s) need sync`);
+  } else if (options.write) console.log(`traceability links: synced ${results.length} file(s)`);
+  else console.log('traceability links: all generated sections are up to date');
+  process.exit(ok ? 0 : 1);
+}
+
 export function parseGraphOptions(argv) {
   const filtered = [];
   let changed;
@@ -1443,6 +1519,7 @@ export function runCli(argv = process.argv.slice(2)) {
   else if (command === 'load-snapshot') runLoadSnapshot(args);
   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 usage(`Unknown command: ${command}`);
 }

package/src/docs/traceability.mjs

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { rel } from '../common/paths.mjs';
+import { defaultMemoryConfig, resolveMemoryArea } from '../memory/config.mjs';
 
 function isSecretIndexPath(path) {
   return /(^|\/)(\.env|\.npmrc|\.pypirc|id_rsa|id_dsa|id_ed25519|credentials|secrets?)(\.|\/|$)/i.test(path);
@@ -8,6 +9,8 @@ function isSecretIndexPath(path) {
 
 const TRACEABILITY_PATH_FIELDS = ['implementedBy', 'verifiedBy', 'relatedDocs'];
 const TRACEABILITY_COMMAND_FIELDS = ['verificationCommands'];
+export const TRACEABILITY_LINKS_START = '<!-- dotdotgod:traceability-links:start version=1 source=json-dotdotgod -->';
+export const TRACEABILITY_LINKS_END = '<!-- dotdotgod:traceability-links:end -->';
 
 export function traceabilityExample() {
   return 'Expected dotdotgod traceability block:\n\n```json dotdotgod\n{\n  "kind": "spec",\n  "implementedBy": ["packages/..."],\n  "verifiedBy": ["packages/..."],\n  "relatedDocs": ["docs/..."],\n  "verificationCommands": ["pnpm ..."]\n}\n```\n\nProperty guidance:\n- kind: use "spec" for behavior specs.\n- implementedBy: source/config/script files that implement this spec\'s behavior.\n- verifiedBy: test files or verification docs that check this behavior.\n- relatedDocs: docs with relevant architecture, test strategy, or product context.\n- verificationCommands: commands an agent can run to verify this behavior.';
@@ -27,9 +30,9 @@ export function extractDotdotgodTraceabilityBlocks(content) {
     const raw = match[3].trim();
     const line = lineForOffset(content, match.index);
     try {
-      blocks.push({ data: JSON.parse(raw), raw, line });
+      blocks.push({ data: JSON.parse(raw), raw, line, index: match.index, end: re.lastIndex });
     } catch (error) {
-      blocks.push({ error: error instanceof Error ? error.message : String(error), raw, line });
+      blocks.push({ error: error instanceof Error ? error.message : String(error), raw, line, index: match.index, end: re.lastIndex });
     }
   }
   return blocks;
@@ -55,7 +58,117 @@ export function validateTraceabilityPlacement(content, root, file) {
   return [];
 }
 
-export function validateTraceabilityBlock(data, root, file, line = null) {
+function allMarkerIndexes(content, marker) {
+  const indexes = [];
+  let index = content.indexOf(marker);
+  while (index !== -1) {
+    indexes.push(index);
+    index = content.indexOf(marker, index + marker.length);
+  }
+  return indexes;
+}
+
+export function findTraceabilityLinksRegion(content) {
+  const starts = allMarkerIndexes(content, TRACEABILITY_LINKS_START);
+  const ends = allMarkerIndexes(content, TRACEABILITY_LINKS_END);
+  if (starts.length === 0 && ends.length === 0) return { status: 'missing' };
+  if (starts.length !== 1 || ends.length !== 1) return { status: 'invalid', code: 'TRACEABILITY_LINKS_MARKER_COUNT', message: 'Traceability links region must contain exactly one start marker and one end marker.' };
+  const start = starts[0];
+  const end = ends[0];
+  if (start > end) return { status: 'invalid', code: 'TRACEABILITY_LINKS_MARKER_ORDER', message: 'Traceability links start marker must appear before the end marker.' };
+  return { status: 'present', start, end: end + TRACEABILITY_LINKS_END.length };
+}
+
+export function validateTraceabilityLinksRegion(content, root, file) {
+  const region = findTraceabilityLinksRegion(content);
+  if (region.status !== 'invalid') return [];
+  return [traceabilityFieldError(rel(root, file), region.code, null, region.message)];
+}
+
+export function stripTraceabilityLinksRegion(content) {
+  const ranges = [];
+  const region = findTraceabilityLinksRegion(content);
+  if (region.status === 'present') ranges.push({ start: region.start, end: region.end });
+  for (const block of extractDotdotgodTraceabilityBlocks(content)) ranges.push({ start: block.index, end: block.end });
+  if (ranges.length === 0) return content;
+  return ranges
+    .sort((a, b) => b.start - a.start)
+    .reduce((next, range) => `${next.slice(0, range.start)}${next.slice(range.end)}`, content);
+}
+
+function markdownLinkPath(root, file, target) {
+  const fromDir = dirname(file);
+  const absoluteTarget = resolve(root, target);
+  let link = relative(fromDir, absoluteTarget).split('\\').join('/');
+  if (!link.startsWith('.') && !link.startsWith('/')) link = link || basename(target);
+  return link;
+}
+
+function escapeMarkdownText(value) {
+  return String(value).replace(/([\\[\\]])/g, '\\$1');
+}
+
+function escapeCodeSpan(value) {
+  return String(value).replace(/`/g, '\\`');
+}
+
+function labelForTraceabilityPath(path) {
+  return path;
+}
+
+function renderPathList(title, paths, root, file) {
+  if (!Array.isArray(paths) || paths.length === 0) return [];
+  const lines = [`- ${title}:`];
+  for (const target of paths) lines.push(`  - [${escapeMarkdownText(labelForTraceabilityPath(target))}](${markdownLinkPath(root, file, target)})`);
+  return lines;
+}
+
+function renderCommandList(commands) {
+  if (!Array.isArray(commands) || commands.length === 0) return [];
+  return ['- Verification commands:', ...commands.map((command) => `  - \`${escapeCodeSpan(command)}\``)];
+}
+
+export function renderTraceabilityLinks(data, root, file) {
+  const body = [
+    '### Traceability Links',
+    '',
+    ...renderPathList('Implemented by', data?.implementedBy, root, file),
+    ...renderPathList('Verified by', data?.verifiedBy, root, file),
+    ...renderPathList('Related docs', data?.relatedDocs, root, file),
+    ...renderCommandList(data?.verificationCommands),
+  ];
+  return `${TRACEABILITY_LINKS_START}\n<!-- generated: do not edit manually -->\n\n${body.join('\n')}\n\n${TRACEABILITY_LINKS_END}`;
+}
+
+export function renderCompactTraceabilityBlock(data) {
+  return `\`\`\`json dotdotgod\n${JSON.stringify(data)}\n\`\`\``;
+}
+
+export function syncTraceabilityLinksInContent(content, data, root, file) {
+  const region = findTraceabilityLinksRegion(content);
+  if (region.status === 'invalid') return { ok: false, changed: false, errors: validateTraceabilityLinksRegion(content, root, file) };
+  const generated = renderTraceabilityLinks(data, root, file);
+  const blocks = extractDotdotgodTraceabilityBlocks(content).filter((block) => !block.error);
+  if (blocks.length === 0) return { ok: false, changed: false, errors: [traceabilityFieldError(rel(root, file), 'TRACEABILITY_LINKS_MISSING_BLOCK', null, 'Cannot generate traceability links without a valid `json dotdotgod` block.')] };
+  const block = blocks.at(-1);
+  const compactBlock = renderCompactTraceabilityBlock(data);
+  let next = `${content.slice(0, block.index)}${compactBlock}${content.slice(block.end)}`;
+  const adjustedRegion = region.status === 'present' && region.start > block.index
+    ? { start: region.start - (block.end - block.index) + compactBlock.length, end: region.end - (block.end - block.index) + compactBlock.length }
+    : region;
+  if (adjustedRegion.status === 'present') {
+    next = `${next.slice(0, adjustedRegion.start)}${generated}${next.slice(adjustedRegion.end)}`;
+    return { ok: true, changed: next !== content, content: next };
+  }
+  const refreshedBlocks = extractDotdotgodTraceabilityBlocks(next).filter((item) => !item.error);
+  const refreshedBlock = refreshedBlocks.at(-1);
+  const prefix = next.slice(0, refreshedBlock.index).replace(/[ \t]*$/u, '');
+  const suffix = next.slice(refreshedBlock.index);
+  next = `${prefix}\n\n${generated}\n\n${suffix}`;
+  return { ok: true, changed: next !== content, content: next };
+}
+
+export function validateTraceabilityBlock(data, root, file, line = null, config = defaultMemoryConfig()) {
   const errors = [];
   const add = (code, field, message) => errors.push(traceabilityFieldError(rel(root, file), code, field, message, line));
   if (!data || typeof data !== 'object' || Array.isArray(data)) {
@@ -73,6 +186,11 @@ export function validateTraceabilityBlock(data, root, file, line = null) {
         add('TRACEABILITY_INVALID_PATH', field, `invalid local relative path: ${JSON.stringify(value)}.`);
         continue;
       }
+      const area = resolveMemoryArea(value, config);
+      if (area?.scope === 'local') {
+        add('TRACEABILITY_LOCAL_MEMORY_TARGET', field, `target points to local memory area "${area.id}": ${value}. Traceability must point to shared durable files, not active plans or archive memory.`);
+        continue;
+      }
       if (!existsSync(resolve(root, value))) add('TRACEABILITY_MISSING_TARGET', field, `target does not exist: ${value}.`);
     }
   }

package/src/load-snapshot/summary.mjs

@@ -54,7 +54,20 @@ export function buildMemoryAreas(index, limits = {}) {
   const config = index?.memoryConfig?.areas ? index.memoryConfig : defaultMemoryConfig();
   const areas = new Map();
   for (const definition of config.areas ?? []) {
-    areas.set(definition.id, { area: definition.id, label: definition.label, role: definition.role, scope: definition.scope, freshness: definition.freshness, priority: definition.priority, includeBodiesByDefault: definition.includeBodiesByDefault !== false, files: [], count: 0, omitted: 0 });
+    areas.set(definition.id, {
+      area: definition.id,
+      label: definition.label,
+      role: definition.role,
+      ...(definition.description ? { description: definition.description } : {}),
+      ...(definition.clarify ? { clarify: definition.clarify } : {}),
+      scope: definition.scope,
+      freshness: definition.freshness,
+      priority: definition.priority,
+      includeBodiesByDefault: definition.includeBodiesByDefault !== false,
+      files: [],
+      count: 0,
+      omitted: 0,
+    });
   }
   for (const node of graph.nodes) {
     if (node.type !== 'file') continue;

package/src/memory/config.mjs

@@ -62,12 +62,32 @@ const DEFAULT_MEMORY_AREAS = [
   { 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 },
 ];
 
-function cloneArea(area) {
+function cloneClarifyGuidance(clarify) {
+  if (!clarify || typeof clarify !== 'object' || Array.isArray(clarify)) return undefined;
+  return {
+    ...(Array.isArray(clarify.audience) ? { audience: [...clarify.audience] } : {}),
+    ...(typeof clarify.documentType === 'string' ? { documentType: clarify.documentType } : {}),
+    ...(typeof clarify.clarityGoal === 'string' ? { clarityGoal: clarify.clarityGoal } : {}),
+    ...(Array.isArray(clarify.editRules) ? { editRules: [...clarify.editRules] } : {}),
+  };
+}
+
+function withOptionalAreaMetadata(target, area) {
+  const description = typeof area.description === 'string' ? area.description.trim() : '';
+  const clarify = cloneClarifyGuidance(area.clarify);
   return {
+    ...target,
+    ...(description ? { description } : {}),
+    ...(clarify && Object.keys(clarify).length > 0 ? { clarify } : {}),
+  };
+}
+
+function cloneArea(area) {
+  return withOptionalAreaMetadata({
     ...area,
     paths: [...(area.paths ?? [])],
     excludePaths: [...(area.excludePaths ?? [])],
-  };
+  }, area);
 }
 
 export function cloneTraceabilityPolicy(policy = DEFAULT_TRACEABILITY_POLICY) {
@@ -216,7 +236,7 @@ export function requiresTraceability(path = '', config = defaultMemoryConfig())
 }
 
 function normalizeMemoryArea(raw) {
-  return {
+  return withOptionalAreaMetadata({
     id: raw.id,
     label: raw.label ?? raw.id,
     paths: Array.isArray(raw.paths) ? raw.paths.map(normalizePathPattern) : [],
@@ -226,7 +246,7 @@ function normalizeMemoryArea(raw) {
     role: raw.role ?? raw.id,
     priority: typeof raw.priority === 'number' ? raw.priority : 30,
     includeBodiesByDefault: raw.includeBodiesByDefault !== false,
-  };
+  }, raw);
 }
 
 function isFiniteNumberInRange(value, min, max) {
@@ -352,6 +372,18 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
     if (!MEMORY_FRESHNESS.has(area.freshness)) add('MEMORY_CONFIG_INVALID_FRESHNESS', `${prefix}.freshness`, 'Expected "fresh" or "stale".');
     if (area.priority !== undefined && (!Number.isInteger(area.priority) || area.priority < 0 || area.priority > 100)) add('MEMORY_CONFIG_INVALID_PRIORITY', `${prefix}.priority`, 'Expected an integer from 0 to 100.');
     if (area.includeBodiesByDefault !== undefined && typeof area.includeBodiesByDefault !== 'boolean') add('MEMORY_CONFIG_INVALID_INCLUDE_POLICY', `${prefix}.includeBodiesByDefault`, 'Expected a boolean.');
+    if (area.description !== undefined && (typeof area.description !== 'string' || !area.description.trim())) add('MEMORY_CONFIG_INVALID_DESCRIPTION', `${prefix}.description`, 'Expected a non-empty string.');
+    if (area.clarify !== undefined) {
+      const clarify = area.clarify;
+      if (!clarify || typeof clarify !== 'object' || Array.isArray(clarify)) {
+        add('MEMORY_CONFIG_INVALID_CLARIFY', `${prefix}.clarify`, 'Expected an object.');
+      } else {
+        if (clarify.audience !== undefined && (!Array.isArray(clarify.audience) || clarify.audience.some((value) => typeof value !== 'string' || !value.trim()))) add('MEMORY_CONFIG_INVALID_CLARIFY_AUDIENCE', `${prefix}.clarify.audience`, 'Expected an array of non-empty strings.');
+        if (clarify.documentType !== undefined && (typeof clarify.documentType !== 'string' || !clarify.documentType.trim())) add('MEMORY_CONFIG_INVALID_CLARIFY_DOCUMENT_TYPE', `${prefix}.clarify.documentType`, 'Expected a non-empty string.');
+        if (clarify.clarityGoal !== undefined && (typeof clarify.clarityGoal !== 'string' || !clarify.clarityGoal.trim())) add('MEMORY_CONFIG_INVALID_CLARITY_GOAL', `${prefix}.clarify.clarityGoal`, 'Expected a non-empty string.');
+        if (clarify.editRules !== undefined && (!Array.isArray(clarify.editRules) || clarify.editRules.some((value) => typeof value !== 'string' || !value.trim()))) add('MEMORY_CONFIG_INVALID_CLARIFY_EDIT_RULES', `${prefix}.clarify.editRules`, 'Expected an array of non-empty strings.');
+      }
+    }
     for (const pattern of area.paths ?? []) {
       if (exactIncluded.has(pattern) && !(area.excludePaths ?? []).includes(pattern)) add('MEMORY_CONFIG_OVERLAP', `${prefix}.paths`, `Path pattern also appears in ${exactIncluded.get(pattern)}: ${pattern}`);
       else exactIncluded.set(pattern, `${prefix}.paths`);
@@ -382,7 +414,7 @@ export function readMemoryConfig(root = '.') {
 }
 
 function serializableMemoryArea(area) {
-  return {
+  return withOptionalAreaMetadata({
     id: area.id,
     label: area.label,
     paths: [...(area.paths ?? [])],
@@ -392,7 +424,7 @@ function serializableMemoryArea(area) {
     role: area.role,
     priority: area.priority,
     includeBodiesByDefault: area.includeBodiesByDefault !== false,
-  };
+  }, area);
 }
 
 export function defaultDotdotgodConfigData() {
@@ -415,17 +447,17 @@ export function defaultDotdotgodConfigText() {
 export function memoryConfigSummary(config) {
   return {
     source: config.source ?? 'default',
-    areas: (config.areas ?? []).map((area) => ({
+    areas: (config.areas ?? []).map((area) => withOptionalAreaMetadata({
       id: area.id,
       label: area.label,
-      paths: area.paths,
-      excludePaths: area.excludePaths ?? [],
+      paths: [...(area.paths ?? [])],
+      excludePaths: [...(area.excludePaths ?? [])],
       scope: area.scope,
       freshness: area.freshness,
       role: area.role,
       priority: area.priority,
       includeBodiesByDefault: area.includeBodiesByDefault !== false,
-    })),
+    }, area)),
     traceability: cloneTraceabilityPolicy(config.traceability ?? DEFAULT_TRACEABILITY_POLICY),
     validation: cloneValidationPolicy(config.validation ?? DEFAULT_VALIDATION_POLICY),
     impactRanking: cloneImpactRankingPolicy(config.impactRanking ?? DEFAULT_IMPACT_RANKING_POLICY),