xdrs-core 0.50.0 → 0.52.0

package/lib/lint.js

@@ -23,13 +23,18 @@ const NUMBERED_FILE_RE = /^(\d{3,})-([a-z0-9-]+)\.md$/;
 // kebab-case; digits are allowed anywhere in the name, including as a prefix.
 const SKILL_DIR_RE = /^[a-z0-9-]+$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRS scopes listed last override the ones listed first';
+// Activation tags and legend per _core-adr-policy-022 rules 03 and 09
+const ACTIVATION_TAGS = new Set(['extends-only', 'disabled']);
+const ACTIVATION_LEGEND_TEXT = 'Scopes tagged `disabled` MUST be ignored; `extends-only` scopes apply only via extends (see _core-adr-policy-022)';
 const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'initiatives']);
 const RESOURCE_DIR_NAME = '.assets';
+const SOURCE_SNAPSHOT_DIR_NAME = 'sources';
+const SOURCE_TRACKING_FILE_NAME = 'source.md';
 const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_DIR_NAME, 'dist']);
 
 const POLICY_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'freeze-reference']);
 const SKILL_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'license', 'metadata']);
-const SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS = new Set(['scope-type', 'name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'follows', 'extends']);
+const SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS = new Set(['scope-type', 'name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'follows', 'extends', 'extends-only']);
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 const SLIDE_FILE_RE = /^.+-slides(?:-[a-z0-9-]+)?\.md$/;
 const SLIDE_MAX_NAME_LENGTH = 64;
@@ -100,13 +105,14 @@ function runLintCli(args) {
     }
   }
 
+  for (const [scopeName, causes] of result.readOnlyScopes) {
+    for (const cause of causes) {
+      console.log(`- READ-ONLY scope "${scopeName}": ${cause}; no changes must be made to this scope [_core-adr-policy-022.06-read-only-dependencies]`);
+    }
+  }
+
   if (result.errors.length === 0) {
     console.log(`Lint passed for ${toDisplayPath(result.xdrsRoot)}`);
-    if (result.readOnlyScopes.size > 0) {
-      for (const scopeName of result.readOnlyScopes) {
-        console.log(`- READ-ONLY scope "${scopeName}": one or more follows -core scopes are not present in this workspace; no changes must be made to this scope [_core-adr-policy-011.08-unavailable-core-read-only]`);
-      }
-    }
     return 0;
   }
 
@@ -142,7 +148,7 @@ function lintWorkspace(targetPath, options = {}) {
   const xdrsRoot = resolveXdrsRoot(resolvedTarget);
   const errors = [];
   const warnings = [];
-  const readOnlyScopes = new Set();
+  const readOnlyScopes = new Map(); // scopeName -> [cause, ...] per _core-adr-policy-022.06
 
   if (!existsDirectory(xdrsRoot)) {
     errors.push(`Missing XDRS root directory: ${toDisplayPath(xdrsRoot)} [_core-adr-policy-001]`);
@@ -158,7 +164,13 @@ function lintWorkspace(targetPath, options = {}) {
   const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDRS root directory');
   const scopeEntries = rootEntries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'));
 
-  // Pass 1: collect known scope-type names from NNN-{scope-type}-scope-type.md files in any scope
+  const rootIndexPath = path.join(xdrsRoot, 'index.md');
+  const activation = existsFile(rootIndexPath) ? parseRootIndexActivation(rootIndexPath, xdrsRoot, errors) : new Map();
+
+  // Pass 1: collect known scope-type names from NNN-{scope-type}-scope-type.md files in any scope,
+  // plus the follows:/extends:/extends-only fields of every scope index (including external scopes)
+  const scopeMeta = new Map(); // scopeName -> readScopeMeta() result (null when index.md is missing)
+  const scopeTypeDefiningScopes = new Map(); // scopeTypeName -> Set(scopeName)
   const knownScopeTypes = new Map(); // scopeTypeName -> filePath (first primary found, for downstream validation)
   const scopeTypePrimaryKeys = new Set(); // "scopeName|typeName|scopeTypeName" for companion co-location checks
   const scopeTypePrimaryByScope = new Map(); // "scopeName|scopeTypeName" -> [typeName, ...] for duplicate detection
@@ -166,6 +178,7 @@ function lintWorkspace(targetPath, options = {}) {
   for (const scopeEntry of scopeEntries) {
     const scopeName = scopeEntry.name;
     const scopePath = path.join(xdrsRoot, scopeName);
+    scopeMeta.set(scopeName, readScopeMeta(path.join(scopePath, 'index.md')));
     for (const typeName of Object.keys(TYPE_TO_ID)) {
       const principlesDir = path.join(scopePath, typeName, 'principles');
       if (!existsDirectory(principlesDir)) continue;
@@ -185,13 +198,17 @@ function lintWorkspace(targetPath, options = {}) {
           if (!knownScopeTypes.has(scopeTypeName)) {
             knownScopeTypes.set(scopeTypeName, filePath);
           }
+          if (!scopeTypeDefiningScopes.has(scopeTypeName)) {
+            scopeTypeDefiningScopes.set(scopeTypeName, new Set());
+          }
+          scopeTypeDefiningScopes.get(scopeTypeName).add(scopeName);
           scopeTypePrimaryKeys.add(`${scopeName}|${typeName}|${scopeTypeName}`);
           const scopeKey = `${scopeName}|${scopeTypeName}`;
           if (!scopeTypePrimaryByScope.has(scopeKey)) {
             scopeTypePrimaryByScope.set(scopeKey, []);
           }
           scopeTypePrimaryByScope.get(scopeKey).push(typeName);
-          validateStructuredFormat(filePath, errors, '_core-adr-policy-010.08b-def-scope-type-must-be-structured');
+          validateStructuredFormat(filePath, errors, '_core-adr-policy-010.11-def-scope-type-must-be-structured');
         } else {
           // Check if it's a companion file: title contains '-scope-type-' followed by a qualifier
           const stIdx = shortTitle.indexOf('-scope-type-');
@@ -200,7 +217,7 @@ function lintWorkspace(targetPath, options = {}) {
             // Special-case: 'local' maps to '_local'
             const scopeTypeName = rawScopeTypeName === 'local' ? '_local' : rawScopeTypeName;
             scopeTypeCompanions.push({ scopeTypeName, scopeName, typeName, filePath });
-            validateStructuredFormat(filePath, errors, '_core-adr-policy-010.08b-def-scope-type-must-be-structured');
+            validateStructuredFormat(filePath, errors, '_core-adr-policy-010.11-def-scope-type-must-be-structured');
           }
         }
       }
@@ -220,7 +237,7 @@ function lintWorkspace(targetPath, options = {}) {
   // Validate: each companion must have a corresponding primary in the same scope and type folder
   for (const { scopeTypeName, scopeName, typeName, filePath } of scopeTypeCompanions) {
     if (!scopeTypePrimaryKeys.has(`${scopeName}|${typeName}|${scopeTypeName}`)) {
-      errors.push(`Companion scope-type file has no corresponding primary "${scopeTypeName}-scope-type" policy in the same scope "${scopeName}" and type folder "${typeName}": ${toDisplayPath(filePath)} [_core-adr-policy-010.02b-companion-requires-primary]`);
+      errors.push(`Companion scope-type file has no corresponding primary "${scopeTypeName}-scope-type" policy in the same scope "${scopeName}" and type folder "${typeName}": ${toDisplayPath(filePath)} [_core-adr-policy-010.03-def-companion-files]`);
     }
   }
 
@@ -230,11 +247,13 @@ function lintWorkspace(targetPath, options = {}) {
     }
   }
 
+  collectReadOnlyScopes(scopeMeta, activation, externalScopes, knownScopeTypes, scopeTypeDefiningScopes, readOnlyScopes);
+
   // Populated during lintScopeIndexFrontmatter: scopeName -> [extendedScopeNames...]
   const extendsRelationships = new Map();
 
   for (const scopeEntry of scopeEntries) {
-    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, warnings, actualTypeIndexes, ignoreExternal, effectiveExternalScopes, knownScopeTypes, readOnlyScopes, extendsRelationships);
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, warnings, actualTypeIndexes, ignoreExternal, effectiveExternalScopes, knownScopeTypes, extendsRelationships, externalScopes);
   }
 
   // Detect cycles in extends: chains (DFS)
@@ -261,17 +280,16 @@ function lintWorkspace(targetPath, options = {}) {
     detectExtendsCycles(scope, []);
   }
 
-  const rootIndexPath = path.join(xdrsRoot, 'index.md');
   if (!existsFile(rootIndexPath)) {
     errors.push('Missing required root index: .xdrs/index.md [_core-adr-policy-001]');
   } else {
-    lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, warnings, effectiveExternalScopes, extendsRelationships);
+    lintRootIndex(rootIndexPath, xdrsRoot, errors, warnings, effectiveExternalScopes, { activation, scopeMeta, knownScopeTypes });
   }
 
   return { xdrsRoot, errors, warnings, readOnlyScopes };
 }
 
-function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, warnings = [], externalScopes = new Set(), extendsRelationships = new Map()) {
+function lintRootIndex(rootIndexPath, xdrsRoot, errors, warnings, externalScopes, ctx) {
   const content = fs.readFileSync(rootIndexPath, 'utf8');
   const repoRoot = path.dirname(xdrsRoot);
 
@@ -290,8 +308,6 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, warni
     }
   }
 
-  const linkedScopeIndexes = links.filter((linkPath) => isScopeIndex(linkPath, xdrsRoot));
-  const linkedSet = new Set(linkedScopeIndexes.map(normalizePath));
   const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
   for (const linkPath of links) {
@@ -300,38 +316,207 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, warni
     }
   }
 
-  // Build set of all scopes referenced via any extends: chain
-  const extendsReferencedScopes = new Set();
-  for (const entries of extendsRelationships.values()) {
-    for (const e of entries) extendsReferencedScopes.add(e);
+  const { activation, scopeMeta, knownScopeTypes } = ctx;
+  const display = toDisplayPath(rootIndexPath);
+  const tagOf = (scopeName) => (activation.get(scopeName) || {}).tag || null;
+
+  // Every scope folder with an index.md (including external scopes), except _local, is linked
+  for (const [scopeName, meta] of scopeMeta) {
+    if (!meta || scopeName === '_local') continue;
+    const fieldTrue = meta.extendsOnly === 'true';
+    const suggestedLine = `[View scope ${scopeName}](${scopeName}/index.md)${fieldTrue ? ' `extends-only`' : ''}`;
+    const entry = activation.get(scopeName);
+    if (!entry) {
+      errors.push(`Root index is missing scope index link: ${toDisplayPath(path.join(xdrsRoot, scopeName, 'index.md'))}; add the line: ${suggestedLine} [_core-adr-policy-022.01-root-index-completeness]`);
+      continue;
+    }
+    if (fieldTrue && !entry.tag) {
+      errors.push(`Scope "${scopeName}" declares extends-only: true, so its root index link on line ${entry.line} must carry an activation tag; change it to: ${suggestedLine} (or tag it \`disabled\`): ${display} [_core-adr-policy-022.07-extends-only-field]`);
+    }
+    if (entry.tag === 'extends-only' && scopeName !== '_core' && isCoreTypeScope(meta.scopeTypes, knownScopeTypes)) {
+      errors.push(`Core-type scope "${scopeName}" must not be tagged \`extends-only\` (line ${entry.line}): ${display} [_core-adr-policy-022.07-extends-only-field]`);
+    }
   }
 
-  // Collect non-_local scopes that have type indexes and check their scope index is linked
-  const scopesWithTypeIndexes = new Set();
-  for (const indexPath of actualTypeIndexes) {
-    const scopeName = path.basename(path.dirname(path.dirname(indexPath)));
-    if (scopeName !== '_local') {
-      scopesWithTypeIndexes.add(scopeName);
+  const hasTags = [...activation.values()].some((entry) => entry.tag);
+  if (hasTags && !content.includes(ACTIVATION_LEGEND_TEXT)) {
+    errors.push(`Root index uses activation tags but is missing the legend line: ${ACTIVATION_LEGEND_TEXT}: ${display} [_core-adr-policy-022.09-root-index-ownership]`);
+  }
+
+  // extends-only scopes must be reached (transitively) through the extends: chain of an active scope
+  const reached = new Set();
+  const visit = (scopeName) => {
+    for (const target of (scopeMeta.get(scopeName) || {}).extends || []) {
+      if (reached.has(target) || !scopeMeta.get(target) || tagOf(target) === 'disabled') continue;
+      reached.add(target);
+      visit(target);
+    }
+  };
+  for (const [scopeName, meta] of scopeMeta) {
+    if (!meta) continue;
+    if (scopeName === '_local' || (activation.has(scopeName) && !tagOf(scopeName))) {
+      visit(scopeName);
+    }
+  }
+  for (const [scopeName, entry] of activation) {
+    if (entry.tag === 'extends-only' && !reached.has(scopeName)) {
+      warnings.push(`Scope "${scopeName}" is tagged \`extends-only\` but no active scope extends it, so its policies never apply: ${display} [_core-adr-policy-022.04-extends-only]`);
+    }
+  }
+}
+
+// Parses root index scope links and their activation tags (_core-adr-policy-022 rules 01 and 03).
+// Returns Map scopeName -> { tag, line }. Links inside fenced code blocks are ignored.
+function parseRootIndexActivation(rootIndexPath, xdrsRoot, errors) {
+  const activation = new Map();
+  const content = fs.readFileSync(rootIndexPath, 'utf8');
+  const repoRoot = path.dirname(xdrsRoot);
+  const baseDir = path.dirname(rootIndexPath);
+  const display = toDisplayPath(rootIndexPath);
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) continue;
+    const line = lines[index];
+    const lineNumber = index + 1;
+    const allowedTagOffsets = new Set();
+    let hasScopeLink = false;
+
+    for (const match of line.matchAll(/!?\[[^\]]+\]\(([^)]+)\)/g)) {
+      const target = normalizeLocalLinkTarget(match[1].trim());
+      if (!target) continue;
+      const linkPath = target.startsWith('/') ? path.join(repoRoot, target) : path.resolve(baseDir, target);
+      if (!isScopeIndex(linkPath, xdrsRoot)) continue;
+      hasScopeLink = true;
+      const scopeName = relativeFrom(xdrsRoot, linkPath).split(path.sep)[0];
+      const linkEnd = match.index + match[0].length;
+      const tagMatch = line.slice(linkEnd).match(/^[ \t]*`([^`]*)`/);
+      let tag = null;
+      if (tagMatch && ACTIVATION_TAGS.has(tagMatch[1])) {
+        tag = tagMatch[1];
+        allowedTagOffsets.add(linkEnd + tagMatch[0].length - tagMatch[1].length - 2);
+      }
+      if (scopeName === '_local') continue; // reported by lintRootIndex
+      if (tag && scopeName === '_core') {
+        errors.push(`Scope "_core" must not carry an activation tag (line ${lineNumber}): ${display} [_core-adr-policy-022.03-activation-tag-syntax]`);
+      }
+      const existing = activation.get(scopeName);
+      if (existing) {
+        errors.push(`Root index links scope "${scopeName}" more than once (lines ${existing.line} and ${lineNumber}); keep a single link: ${display} [_core-adr-policy-022.01-root-index-completeness]`);
+      } else {
+        activation.set(scopeName, { tag, line: lineNumber });
+      }
+    }
+
+    if (!hasScopeLink) continue;
+    for (const span of line.matchAll(/`[^`]*`/g)) {
+      if (!allowedTagOffsets.has(span.index)) {
+        errors.push(`Root index line ${lineNumber} has invalid inline code ${span[0]}: a scope link line may only carry one activation tag (\`extends-only\` or \`disabled\`, lowercase) right after the link: ${display} [_core-adr-policy-022.03-activation-tag-syntax]`);
+      }
     }
   }
 
-  for (const scopeName of scopesWithTypeIndexes) {
-    const scopeIndexPath = normalizePath(path.join(xdrsRoot, scopeName, 'index.md'));
-    if (!linkedSet.has(scopeIndexPath)) {
-      // Exempt scopes that are only reachable via extends: chains
-      if (extendsReferencedScopes.has(scopeName)) {
-        // Scope is extends-only (not in root index) — exempt from mandatory link requirement
-        // No warning here: absence from root index is expected and valid for extends-only scopes
+  return activation;
+}
+
+// Reads the fields of a scope index needed before per-scope lint runs (including external scopes).
+// Returns null when the scope has no readable index.md.
+function readScopeMeta(scopeIndexPath) {
+  if (!existsFile(scopeIndexPath)) return null;
+  let content;
+  try { content = fs.readFileSync(scopeIndexPath, 'utf8'); } catch { return null; }
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const block = fmMatch ? fmMatch[1] : '';
+  const listField = (key) => {
+    const lineMatch = block.match(new RegExp(`^${key}:[ \\t]*(.*)`, 'm'));
+    return lineMatch ? deriveScopeNameListEntries(block, lineMatch, lineMatch[1].trim()) : [];
+  };
+  const scopeTypeMatch = block.match(/^scope-type:[ \t]*(.+)$/m);
+  const extendsOnlyMatch = block.match(/^extends-only:[ \t]*(.*)$/m);
+  return {
+    hasFrontmatter: Boolean(fmMatch),
+    scopeTypes: scopeTypeMatch ? parseScopeTypeField(scopeTypeMatch[1].trim()) : [],
+    follows: listField('follows'),
+    extends: listField('extends'),
+    extendsOnly: extendsOnlyMatch ? extendsOnlyMatch[1].trim() : null,
+  };
+}
+
+// Computes read-only scopes and their causes per _core-adr-policy-022.06. Missing dependencies of
+// local scopes are reported as lint errors elsewhere; here they only make external scopes read-only.
+function collectReadOnlyScopes(scopeMeta, activation, externalScopes, knownScopeTypes, scopeTypeDefiningScopes, readOnlyScopes) {
+  const isDisabled = (scopeName) => (activation.get(scopeName) || {}).tag === 'disabled';
+  for (const [scopeName, meta] of scopeMeta) {
+    if (!meta) continue;
+    const isExternal = externalScopes.has(scopeName);
+    const causes = [];
+    if (isExternal && !meta.hasFrontmatter) {
+      causes.push('its scope index has no frontmatter; fix it in the source package');
+    }
+    if (isExternal && meta.extendsOnly !== null && meta.extendsOnly !== 'true' && meta.extendsOnly !== 'false') {
+      causes.push(`its scope index has an invalid extends-only value "${meta.extendsOnly}" (treated as absent); fix it in the source package`);
+    }
+    if (isExternal && meta.hasFrontmatter && meta.scopeTypes.length === 0) {
+      causes.push('its scope index has no scope-type; fix it in the source package');
+    }
+    for (const [field, targets] of [['follows', meta.follows], ['extends', meta.extends]]) {
+      for (const target of targets) {
+        if (target === scopeName || RESERVED_SCOPES.has(target)) continue;
+        const targetMeta = scopeMeta.get(target);
+        if (!targetMeta) {
+          if (isExternal) causes.push(`${field}: scope "${target}" is not present in this workspace; install it`);
+        } else if (isDisabled(target)) {
+          causes.push(`${field}: scope "${target}" is tagged \`disabled\` in the root index; enable it or remove the ${field}: reference`);
+        } else if (!targetMeta.hasFrontmatter) {
+          causes.push(`${field}: scope "${target}" has an invalid scope index; fix it`);
+        }
+      }
+    }
+    for (const scopeType of resolveScopeTypeChain(meta.scopeTypes, knownScopeTypes)) {
+      if (scopeType === '_local') continue;
+      if (!knownScopeTypes.has(scopeType)) {
+        if (isExternal) causes.push(`scope type "${scopeType}" has no ${scopeType}-scope-type policy in this workspace; install the scope that defines it`);
         continue;
       }
-      errors.push(`Root index is missing scope index link: ${toDisplayPath(path.join(xdrsRoot, scopeName, 'index.md'))} [_core-adr-policy-001]`);
-    } else if (extendsReferencedScopes.has(scopeName)) {
-      // Scope is in BOTH root index and extends chain — ambiguous dual precedence
-      warnings.push(`Scope "${scopeName}" appears in both the root index and an extends: chain; precedence may be ambiguous for consumers that do not follow extends declarations: ${toDisplayPath(path.join(xdrsRoot, scopeName, 'index.md'))} [_core-adr-policy-010.35-extends-index]`);
+      const definers = [...scopeTypeDefiningScopes.get(scopeType)].filter((s) => s !== scopeName);
+      if (definers.length > 0 && definers.every(isDisabled)) {
+        causes.push(`scope type "${scopeType}" is defined only in disabled scope(s) ${definers.map((s) => `"${s}"`).join(', ')}; enable one of them`);
+      }
+    }
+    if (causes.length > 0) {
+      readOnlyScopes.set(scopeName, causes);
     }
   }
 }
 
+// Parses a scope-type value in either "a, b" or "[a, b]" form into its elements.
+function parseScopeTypeField(raw) {
+  const inner = raw.startsWith('[') && raw.endsWith(']') ? raw.slice(1, -1) : raw;
+  return inner.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+// Resolves the flat scope-type chain (declared types plus all parent types, deduplicated) using
+// _core-adr-policy-010.09 parent declarations. Types without a known policy end their chain.
+function resolveScopeTypeChain(scopeTypes, knownScopeTypes) {
+  const chain = [];
+  const seen = new Set();
+  for (const scopeType of scopeTypes) {
+    let current = scopeType;
+    while (current && !seen.has(current)) {
+      seen.add(current);
+      chain.push(current);
+      const policyPath = knownScopeTypes.get(current);
+      current = policyPath ? extractParentScopeType(policyPath) : null;
+    }
+  }
+  return chain;
+}
+
+function isCoreTypeScope(scopeTypes, knownScopeTypes) {
+  return resolveScopeTypeChain(scopeTypes, knownScopeTypes).includes('core');
+}
+
 function lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors, externalScopes = new Set()) {
   const content = fs.readFileSync(scopeIndexPath, 'utf8');
   const repoRoot = path.dirname(xdrsRoot);
@@ -368,7 +553,59 @@ function extractParentScopeType(policyFilePath) {
   return bodyMatch ? bodyMatch[1] : null;
 }
 
-function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes = new Map(), readOnlyScopes = new Set(), extendsRelationships = new Map()) {
+// Parse a scope-type frontmatter value into its individual elements. Supports a single
+// value or a comma-separated list (e.g. "compiled, internal-docs"), matching the grammar
+// defined in _core-adr-policy-010 rules 06 and 07.
+function parseScopeTypeList(raw) {
+  const commaSeparatedScopeTypePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*(?:\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
+  return commaSeparatedScopeTypePattern.test(raw) ? raw.split(',').map((s) => s.trim()) : [raw];
+}
+
+// Shared by the follows:/extends: frontmatter fields, which both accept a scope name, a
+// comma-separated list of scope names, or an indented YAML list of scope names.
+const SCOPE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+const SCOPE_NAME_LIST_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_-]*(?:\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
+
+// Parses the indented "- item" list entries following a scalar-less field line (e.g. a
+// `follows:` key with no inline value). Returns raw trimmed strings in order, including empty
+// ones for bare "-" markers so callers can distinguish "no items" from "blank item".
+function parseYamlListItems(block, lineMatch) {
+  const items = [];
+  const start = block.indexOf(lineMatch[0]) + lineMatch[0].length;
+  for (const line of block.slice(start).split('\n')) {
+    const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
+    if (itemMatch) {
+      items.push((itemMatch[1] || '').trim());
+    } else if (line.trim() && !/^\s/.test(line)) {
+      break;
+    }
+  }
+  return items;
+}
+
+// Validates the raw shape of a follows:/extends: frontmatter field (inline scalar, inline
+// comma-separated list, or indented YAML list). Returns 'empty' when the field has no usable
+// value, 'item' when a list entry is blank or not a valid scope name, or null when valid.
+function validateScopeNameListFormat(block, lineMatch, inlineValue) {
+  if (inlineValue) {
+    return (SCOPE_NAME_PATTERN.test(inlineValue) || SCOPE_NAME_LIST_PATTERN.test(inlineValue)) ? null : 'empty';
+  }
+  const items = parseYamlListItems(block, lineMatch);
+  if (items.length === 0) return 'empty';
+  return items.some((item) => !item || !SCOPE_NAME_PATTERN.test(item)) ? 'item' : null;
+}
+
+// Derives the final array of entry names declared in a follows:/extends: frontmatter field.
+function deriveScopeNameListEntries(block, lineMatch, inlineValue) {
+  if (inlineValue) {
+    if (SCOPE_NAME_LIST_PATTERN.test(inlineValue)) return inlineValue.split(',').map((s) => s.trim());
+    return SCOPE_NAME_PATTERN.test(inlineValue) ? [inlineValue] : [];
+  }
+  return parseYamlListItems(block, lineMatch).filter(Boolean);
+}
+
+function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes = new Map(), extendsRelationships = new Map(), externalScopes = new Set()) {
+  const isExternal = externalScopes.has(scopeName);
   const content = fs.readFileSync(scopeIndexPath, 'utf8');
   const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
   if (!fmMatch) {
@@ -387,18 +624,15 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
   const scopeTypeMatch = block.match(/^scope-type:\s*(.+)$/m);
   const scopeTypeRaw = scopeTypeMatch ? scopeTypeMatch[1].trim() : null;
   if (!scopeTypeRaw) {
-    errors.push(`Scope index frontmatter must include a scope-type field: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.08-def-valid-iff-policy-exists]`);
+    // External scopes with no scope-type become read-only instead (_core-adr-policy-022.06)
+    if (!isExternal) {
+      errors.push(`Scope index frontmatter must include a scope-type field: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.10-def-valid-iff-policy-exists]`);
+    }
     return;
   }
 
   // Parse scope-type: supports single string or comma-separated list (e.g. "compiled, internal-docs")
-  const commaSeparatedScopeTypePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*(?:\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
-  let scopeTypes;
-  if (commaSeparatedScopeTypePattern.test(scopeTypeRaw)) {
-    scopeTypes = scopeTypeRaw.split(',').map((s) => s.trim());
-  } else {
-    scopeTypes = [scopeTypeRaw];
-  }
+  const scopeTypes = parseScopeTypeList(scopeTypeRaw);
 
   // Validate each element: no duplicates, valid chars, no reserved prefix
   const seenTypes = new Set();
@@ -406,17 +640,17 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
   const SCOPE_TYPE_ELEMENT_RE = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
   for (const scopeType of scopeTypes) {
     if (!SCOPE_TYPE_ELEMENT_RE.test(scopeType)) {
-      errors.push(`Scope type element "${scopeType}" contains invalid characters (must match [a-zA-Z_][a-zA-Z0-9_-]*): ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.06-def-no-underscore-prefix]`);
+      errors.push(`Scope type element "${scopeType}" contains invalid characters (must match [a-zA-Z_][a-zA-Z0-9_-]*): ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.08-def-no-underscore-prefix]`);
       hasElementError = true;
       continue;
     }
     if (scopeType.startsWith('_') && scopeType !== '_local') {
-      errors.push(`Scope type "${scopeType}" uses a reserved "_" prefix; only "_local" is a valid underscore-prefixed scope type: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.06-def-no-underscore-prefix]`);
+      errors.push(`Scope type "${scopeType}" uses a reserved "_" prefix; only "_local" is a valid underscore-prefixed scope type: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.08-def-no-underscore-prefix]`);
       hasElementError = true;
       continue;
     }
     if (seenTypes.has(scopeType)) {
-      errors.push(`Scope type list contains duplicate value "${scopeType}": ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.05b-def-multi-type-validation]`);
+      errors.push(`Scope type list contains duplicate value "${scopeType}": ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.07-def-multi-type-validation]`);
       hasElementError = true;
       continue;
     }
@@ -432,7 +666,9 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
   for (const st of scopeTypes) {
     if (st === '_local') continue;
     if (!knownScopeTypes.has(st)) {
-      errors.push(`Scope index scope-type "${st}" has no corresponding ${st}-scope-type policy in the principles of any scope: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.08-def-valid-iff-policy-exists]`);
+      if (!isExternal) {
+        errors.push(`Scope index scope-type "${st}" has no corresponding ${st}-scope-type policy in the principles of any scope: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.10-def-valid-iff-policy-exists]`);
+      }
       continue;
     }
     // Validate parent chain
@@ -443,11 +679,13 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
       const parentType = extractParentScopeType(policyPath);
       if (!parentType) break;
       if (globalVisited.has(parentType)) {
-        errors.push(`Scope type "${currentType}" declares parent "${parentType}" which creates a cycle in the scope-type inheritance chain: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.07-def-parent-scope-type]`);
+        errors.push(`Scope type "${currentType}" declares parent "${parentType}" which creates a cycle in the scope-type inheritance chain: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.09-def-parent-scope-type]`);
         break;
       }
       if (!knownScopeTypes.has(parentType)) {
-        errors.push(`Scope type "${currentType}" declares parent "${parentType}" but no ${parentType}-scope-type policy exists in any scope: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.07-def-parent-scope-type]`);
+        if (!isExternal) {
+          errors.push(`Scope type "${currentType}" declares parent "${parentType}" but no ${parentType}-scope-type policy exists in any scope: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.09-def-parent-scope-type]`);
+        }
         break;
       }
       globalVisited.add(parentType);
@@ -460,7 +698,11 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
   if (scopeName === '_local' && scopeType !== '_local') {
     errors.push(`Scope "_local" must have scope-type "_local": ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-015.01-scope-type-name]`);
   }
-  if (scopeTypes.includes('core') && !scopeName.includes('core')) {
+  const isCoreType = isCoreTypeScope(scopeTypes, knownScopeTypes);
+  if (isCoreType && scopeTypes.length > 1) {
+    errors.push(`Core-type scope must declare exactly one scope type (found "${scopeTypes.join(', ')}"): ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-011.10-no-type-combination]`);
+  }
+  if (isCoreType && !scopeName.includes('core')) {
     errors.push(`Scope with type "core" must have "core" in its name: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-011.03-naming-convention]`);
   }
   if (scopeTypes.includes('_local') && scopeName !== '_local') {
@@ -473,6 +715,19 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
     errors.push(`Scope with type "platform" must follow the naming pattern {domain}-plat-{name} (e.g. "cloud-plat-aws"): ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-013.03-naming-convention]`);
   }
 
+  const extendsOnlyMatch = block.match(/^extends-only:[ \t]*(.*)$/m);
+  if (extendsOnlyMatch) {
+    const extendsOnlyValue = extendsOnlyMatch[1].trim();
+    if (extendsOnlyValue !== 'true' && extendsOnlyValue !== 'false') {
+      // External scopes with an invalid value become read-only instead (_core-adr-policy-022.06)
+      if (!isExternal) {
+        errors.push(`Scope index frontmatter extends-only must be unquoted lowercase true or false (found "${extendsOnlyValue}"): ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-022.07-extends-only-field]`);
+      }
+    } else if (extendsOnlyValue === 'true' && (RESERVED_SCOPES.has(scopeName) || isCoreType)) {
+      errors.push(`Scope index frontmatter extends-only: true is not allowed on _core, _local or core-type scopes: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-022.07-extends-only-field]`);
+    }
+  }
+
   if (!fm.name) {
     errors.push(`Scope index frontmatter must include a non-empty name field: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
   } else if (fm.name !== scopeName) {
@@ -506,49 +761,14 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
   const followsLineMatch = block.match(/^follows:[ \t]*(.*)/m);
   if (followsLineMatch !== null) {
     const followsValue = followsLineMatch[1].trim();
-    const scopeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
-    const commaSeparatedPattern = /^[a-zA-Z_][a-zA-Z0-9_-]*(\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
-    if (followsValue) {
-      if (!scopeNamePattern.test(followsValue) && !commaSeparatedPattern.test(followsValue)) {
-        errors.push(`Scope index frontmatter follows must be a core scope name or list of core scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
-      }
-    } else {
-      const followsStart = block.indexOf(followsLineMatch[0]) + followsLineMatch[0].length;
-      const listItems = [];
-      let hasInvalidEntry = false;
-      for (const line of block.slice(followsStart).split('\n')) {
-        const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
-        if (itemMatch) {
-          const item = (itemMatch[1] || '').trim();
-          if (!item || !scopeNamePattern.test(item)) {
-            errors.push(`Scope index frontmatter follows entries must be non-empty scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
-            hasInvalidEntry = true;
-            break;
-          }
-          listItems.push(item);
-        } else if (line.trim() && !/^\s/.test(line)) {
-          break;
-        }
-      }
-      if (!hasInvalidEntry && listItems.length === 0) {
-        errors.push(`Scope index frontmatter follows must be a core scope name or list of core scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
-      }
+    const followsFormatError = validateScopeNameListFormat(block, followsLineMatch, followsValue);
+    if (followsFormatError === 'item') {
+      errors.push(`Scope index frontmatter follows entries must be non-empty scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
+    } else if (followsFormatError === 'empty') {
+      errors.push(`Scope index frontmatter follows must be a core scope name or list of core scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
     }
     if (xdrsRoot) {
-      const entries = followsValue
-        ? (commaSeparatedPattern.test(followsValue)
-            ? followsValue.split(',').map((s) => s.trim())
-            : [followsValue])
-        : (() => {
-          const items = [];
-          const followsStart = block.indexOf(followsLineMatch[0]) + followsLineMatch[0].length;
-          for (const line of block.slice(followsStart).split('\n')) {
-            const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
-            if (itemMatch && itemMatch[1]) items.push(itemMatch[1].trim());
-            else if (line.trim() && !/^\s/.test(line)) break;
-          }
-          return items;
-        })();
+      const entries = deriveScopeNameListEntries(block, followsLineMatch, followsValue);
       followsEntries = entries;
       const seenFollows = new Set();
       for (const entry of entries) {
@@ -556,7 +776,7 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
           errors.push(`Scope index frontmatter follows has duplicate entry "${entry}": ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
         }
         seenFollows.add(entry);
-        if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry)) {
+        if (SCOPE_NAME_PATTERN.test(entry)) {
           if (entry === scopeName) {
             errors.push(`Scope index frontmatter follows must not reference the scope itself: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
             continue;
@@ -567,11 +787,16 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
           }
           const followedIndexPath = path.join(xdrsRoot, entry, 'index.md');
           if (!existsFile(followedIndexPath)) {
-            errors.push(`Scope index frontmatter follows references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
+            // Missing -core is expected for an external companion scope: it becomes read-only
+            // (collected by collectReadOnlyScopes per _core-adr-policy-022.06), not a lint error.
+            if (!isExternal) {
+              errors.push(`Scope index frontmatter follows references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
+            }
           } else {
             const followedContent = fs.readFileSync(followedIndexPath, 'utf8');
             const followedTypeMatch = followedContent.match(/^scope-type:\s*(.+)$/m);
-            if (!followedTypeMatch || followedTypeMatch[1].trim() !== 'core') {
+            const followedTypes = followedTypeMatch ? parseScopeTypeField(followedTypeMatch[1].trim()) : [];
+            if (!isCoreTypeScope(followedTypes, knownScopeTypes)) {
               errors.push(`Scope index frontmatter follows references scope "${entry}" which is not a core-type scope: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
             }
           }
@@ -585,48 +810,13 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
   const extendsLineMatch = block.match(/^extends:[ \t]*(.*)/m);
   if (extendsLineMatch !== null) {
     const extendsValue = extendsLineMatch[1].trim();
-    const scopeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
-    const commaSeparatedPattern = /^[a-zA-Z_][a-zA-Z0-9_-]*(?:\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
-    if (extendsValue) {
-      if (!scopeNamePattern.test(extendsValue) && !commaSeparatedPattern.test(extendsValue)) {
-        errors.push(`Scope index frontmatter extends must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
-      }
-    } else {
-      const extendsStart = block.indexOf(extendsLineMatch[0]) + extendsLineMatch[0].length;
-      const listItems = [];
-      let hasInvalidEntry = false;
-      for (const line of block.slice(extendsStart).split('\n')) {
-        const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
-        if (itemMatch) {
-          const item = (itemMatch[1] || '').trim();
-          if (!item || !scopeNamePattern.test(item)) {
-            errors.push(`Scope index frontmatter extends entries must be non-empty scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
-            hasInvalidEntry = true;
-            break;
-          }
-          listItems.push(item);
-        } else if (line.trim() && !/^\s/.test(line)) {
-          break;
-        }
-      }
-      if (!hasInvalidEntry && listItems.length === 0) {
-        errors.push(`Scope index frontmatter extends must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
-      }
+    const extendsFormatError = validateScopeNameListFormat(block, extendsLineMatch, extendsValue);
+    if (extendsFormatError === 'item') {
+      errors.push(`Scope index frontmatter extends entries must be non-empty scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
+    } else if (extendsFormatError === 'empty') {
+      errors.push(`Scope index frontmatter extends must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
     }
-    const rawEntries = extendsValue
-      ? (commaSeparatedPattern.test(extendsValue)
-          ? extendsValue.split(',').map((s) => s.trim())
-          : (scopeNamePattern.test(extendsValue) ? [extendsValue] : []))
-      : (() => {
-        const items = [];
-        const extendsStart = block.indexOf(extendsLineMatch[0]) + extendsLineMatch[0].length;
-        for (const line of block.slice(extendsStart).split('\n')) {
-          const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
-          if (itemMatch && itemMatch[1]) items.push(itemMatch[1].trim());
-          else if (line.trim() && !/^\s/.test(line)) break;
-        }
-        return items;
-      })();
+    const rawEntries = deriveScopeNameListEntries(block, extendsLineMatch, extendsValue);
     const seenExtends = new Set();
     for (const entry of rawEntries) {
       if (seenExtends.has(entry)) {
@@ -634,7 +824,7 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
         continue;
       }
       seenExtends.add(entry);
-      if (!scopeNamePattern.test(entry)) continue;
+      if (!SCOPE_NAME_PATTERN.test(entry)) continue;
       if (entry === scopeName) {
         errors.push(`Scope index frontmatter extends must not reference the scope itself: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.30-extends-no-self]`);
         continue;
@@ -655,7 +845,9 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
           continue;
         }
         if (!existsFile(path.join(xdrsRoot, entry, 'index.md'))) {
-          errors.push(`Scope index frontmatter extends references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.32-extends-mandatory-presence]`);
+          if (!isExternal) {
+            errors.push(`Scope index frontmatter extends references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.32-extends-mandatory-presence]`);
+          }
         }
       }
       if (extendsEntries.length > 0) {
@@ -666,7 +858,7 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
 }
 
 
-function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeIndexes, ignoreExternal, externalScopes, knownScopeTypes = new Map(), readOnlyScopes = new Set(), extendsRelationships = new Map()) {
+function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeIndexes, ignoreExternal, externalScopes, knownScopeTypes = new Map(), extendsRelationships = new Map(), trackedExternalScopes = new Set()) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
   if (ignoreExternal && externalScopes.has(scopeName)) {
@@ -688,12 +880,8 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeInd
         const idxContent = fs.readFileSync(scopeIndexPath, 'utf8');
         const stMatch = idxContent.match(/^scope-type:\s*(.+)$/m);
         if (stMatch) {
-          const stRaw = stMatch[1].trim();
-          // Handle both "[type1, type2]" YAML array format and "type1, type2" inline CSV format
-          const stList = stRaw.startsWith('[') && stRaw.endsWith(']')
-            ? stRaw.slice(1, -1).split(',').map((s) => s.trim())
-            : stRaw.split(',').map((s) => s.trim());
-          isCoreTypeNonExempt = stList.includes('core');
+          const stList = parseScopeTypeField(stMatch[1].trim());
+          isCoreTypeNonExempt = isCoreTypeScope(stList, knownScopeTypes);
           isCompiledScope = stList.includes('compiled');
         }
       } catch { /* ignore read errors; will be caught later */ }
@@ -729,7 +917,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeInd
     errors.push(`Missing required scope index: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
   } else {
     lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors, externalScopes);
-    lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes, readOnlyScopes, extendsRelationships);
+    lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes, extendsRelationships, trackedExternalScopes);
   }
   lintLocalMetaPolicies(xdrsRoot, scopeName, errors, isCompiledScope);
 }
@@ -767,22 +955,61 @@ function lintLocalMetaPolicies(xdrsRoot, scopeName, errors, isCompiledScope = fa
     // Error: companion exists without primary in same type folder
     for (const companion of companionsInFolder) {
       if (!primaryInFolder) {
-        errors.push(`Local meta-policy companion "${path.basename(companion.filePath)}" requires a primary "NNN-core.md" in the same type folder "${typeName}": ${toDisplayPath(companion.filePath)} [_core-adr-policy-010.10b-local-primary-required]`);
+        errors.push(`Local meta-policy companion "${path.basename(companion.filePath)}" requires a primary "NNN-core.md" in the same type folder "${typeName}": ${toDisplayPath(companion.filePath)} [_core-adr-policy-010.15-local-primary-required]`);
       }
     }
-    // For compiled scopes: primary meta-policy must include ## Sources and ## Selectors
+    // For compiled scopes: primary meta-policy must include ## Sources, ## Selectors, and ## Sync Settings
     if (isCompiledScope && primaryInFolder) {
       let metaContent;
       try { metaContent = fs.readFileSync(primaryInFolder.filePath, 'utf8'); } catch { /* will be caught elsewhere */ }
       if (metaContent !== undefined) {
         const metaLines = metaContent.split(/\r?\n/);
         const metaIgnored = findIgnoredMarkdownLines(metaLines);
-        if (findHeadingLine(metaLines, metaIgnored, '## Sources') === -1) {
+        const metaHeadingLines = findHeadingLines(metaLines, metaIgnored);
+
+        const sourcesHeadingIdx = findHeadingLine(metaLines, metaIgnored, '## Sources');
+        if (sourcesHeadingIdx === -1) {
           errors.push(`Compiled scope meta-policy must include a "## Sources" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+        } else {
+          const [sourcesStart, sourcesEnd] = sectionBodyRange(metaLines, metaHeadingLines, sourcesHeadingIdx);
+          for (let i = sourcesStart; i < sourcesEnd; i += 1) {
+            if (metaIgnored[i]) continue;
+            const trimmed = metaLines[i].trim();
+            if (!trimmed.startsWith('-')) continue;
+            if (!/^-\s+\[(web|git|local)\]\s+[a-z0-9-]+:\s+.+$/.test(trimmed)) {
+              errors.push(`Compiled scope "## Sources" bullet must include a NAME slug in the format "- [web|git|local] name: value": ${toDisplayPath(primaryInFolder.filePath)}:${i + 1} [_core-adr-policy-019.07-compilation-meta-policy]`);
+            }
+          }
         }
+
         if (findHeadingLine(metaLines, metaIgnored, '## Selectors') === -1) {
           errors.push(`Compiled scope meta-policy must include a "## Selectors" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
         }
+
+        const syncHeadingIdx = findHeadingLine(metaLines, metaIgnored, '## Sync Settings');
+        if (syncHeadingIdx === -1) {
+          errors.push(`Compiled scope meta-policy must include a "## Sync Settings" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+        } else {
+          const [syncStart, syncEnd] = sectionBodyRange(metaLines, metaHeadingLines, syncHeadingIdx);
+          let hasValidResyncPeriod = false;
+          for (let i = syncStart; i < syncEnd; i += 1) {
+            if (metaIgnored[i]) continue;
+            const trimmed = metaLines[i].trim();
+            if (!trimmed.startsWith('-')) continue;
+            const periodMatch = trimmed.match(/^-\s+Source re-sync period days:\s*(\d+)\s*$/);
+            if (periodMatch) {
+              hasValidResyncPeriod = Number(periodMatch[1]) > 0;
+              continue;
+            }
+            const storageMatch = trimmed.match(/^-\s+Source storage:\s*(.+)$/);
+            if (storageMatch && storageMatch[1].trim() !== 'temporary') {
+              errors.push(`Compiled scope "## Sync Settings" "Source storage" value must be "temporary" if present: ${toDisplayPath(primaryInFolder.filePath)}:${i + 1} [_core-adr-policy-019.07-compilation-meta-policy]`);
+            }
+          }
+          if (!hasValidResyncPeriod) {
+            errors.push(`Compiled scope "## Sync Settings" section must include a "Source re-sync period days: N" bullet with a positive integer: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+          }
+        }
       }
     }
     // Check qualifier uniqueness across all type folders
@@ -791,12 +1018,12 @@ function lintLocalMetaPolicies(xdrsRoot, scopeName, errors, isCompiledScope = fa
       const existing = seenQualifiers.get(qualifier);
       if (existing) {
         const label = qualifier === '' ? 'primary (no qualifier)' : `qualifier "${qualifier}"`;
-        errors.push(`Local meta-policy ${label} appears in multiple type folders in scope "${scopeName}": ${toDisplayPath(existing)} and ${toDisplayPath(filePath)} [_core-adr-policy-010.10c-local-unique-qualifier]`);
+        errors.push(`Local meta-policy ${label} appears in multiple type folders in scope "${scopeName}": ${toDisplayPath(existing)} and ${toDisplayPath(filePath)} [_core-adr-policy-010.16-local-unique-qualifier]`);
       } else {
         seenQualifiers.set(qualifier, filePath);
       }
       // Validate structured format for all local meta-policy files
-      validateStructuredFormat(filePath, errors, '_core-adr-policy-010.12b-local-must-be-structured');
+      validateStructuredFormat(filePath, errors, '_core-adr-policy-010.19-local-must-be-structured');
     }
   }
 }
@@ -884,7 +1111,7 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNu
 
   const subjectAssetsDir = path.join(subjectPath, RESOURCE_DIR_NAME);
   const xdrsDocsInSubject = artifacts.filter((p) => path.dirname(p) === subjectPath);
-  lintOrphanAssets(subjectAssetsDir, xdrsDocsInSubject, xdrsRoot, errors);
+  lintOrphanAssets(subjectAssetsDir, xdrsDocsInSubject, xdrsRoot, errors, isCompiledScope);
 
   return artifacts;
 }
@@ -922,7 +1149,7 @@ function lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, filePat
   // Enforce 'core' word reservation: only allowed as first word of filename title in principles/
   const titleParts = match[2].split('-');
   if (titleParts.includes('core') && !(subjectName === 'principles' && titleParts[0] === 'core')) {
-    const msg = `Policy filename must not use "core" as a name word unless it is a local meta-policy in "principles/" starting with "core" (e.g., "NNN-core.md" or "NNN-core-{qualifier}.md"): ${toDisplayPath(filePath)} [_core-adr-policy-010.09-local-naming]`;
+    const msg = `Policy filename must not use "core" as a name word unless it is a local meta-policy in "principles/" starting with "core" (e.g., "NNN-core.md" or "NNN-core-{qualifier}.md"): ${toDisplayPath(filePath)} [_core-adr-policy-010.13-local-naming]`;
     if (freezeReference) { warnings.push(`${msg} [exempt: freeze-reference]`); } else { errors.push(msg); }
   }
 
@@ -930,7 +1157,7 @@ function lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, filePat
     || `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${match[2]}`;
   lintXdrsElementFrontmatter(content, expectedName, filePath, errors, warnings, freezeReference);
   if (enforceStructured) {
-    validateStructuredFormatContent(content, filePath, errors, '_core-adr-policy-010.08c-def-core-scope-policies-must-be-structured');
+    validateStructuredFormatContent(content, filePath, errors, '_core-adr-policy-010.12-def-core-scope-policies-must-be-structured');
   } else if (isCompiledScope) {
     validateStructuredFormatContent(content, filePath, errors, '_core-adr-policy-019.04-structured-format-required');
   } else {
@@ -1833,11 +2060,16 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors, externalScopes =
   }
 }
 
-function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
+function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors, isCompiledScope = false) {
   if (!existsDirectory(assetsDir)) {
     return;
   }
 
+  const sourcesDir = path.join(assetsDir, SOURCE_SNAPSHOT_DIR_NAME);
+  if (isCompiledScope) {
+    lintSourceSnapshotTracking(sourcesDir, errors);
+  }
+
   const assetTree = collectAssetTree(assetsDir, errors);
   if (assetTree.files.length === 0 && assetTree.directories.length === 0) {
     return;
@@ -1859,6 +2091,9 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
   }
 
   for (const assetPath of assetTree.files) {
+    if (isCompiledScope && isPathInside(sourcesDir, assetPath)) {
+      continue;
+    }
     if (!referencedAssets.has(assetPath)) {
       errors.push(`Orphan asset file not referenced by any document: ${toDisplayPath(assetPath)} [_core-adr-policy-001]`);
     }
@@ -1866,6 +2101,9 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
 
   // Lint slide/presentation files inside .assets
   for (const assetPath of assetTree.files) {
+    if (isCompiledScope && isPathInside(sourcesDir, assetPath)) {
+      continue;
+    }
     const fileName = path.basename(assetPath);
     if (SLIDE_FILE_RE.test(fileName)) {
       lintSlideFile(assetPath, documentPaths, xdrsRoot, errors);
@@ -1873,6 +2111,47 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
   }
 }
 
+function lintSourceSnapshotTracking(sourcesDir, errors) {
+  if (!existsDirectory(sourcesDir)) {
+    return;
+  }
+
+  const entries = safeReadDir(sourcesDir, errors, `read source snapshot directory ${toDisplayPath(sourcesDir)}`);
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const trackingFilePath = path.join(sourcesDir, entry.name, SOURCE_TRACKING_FILE_NAME);
+    if (!existsFile(trackingFilePath)) {
+      errors.push(`Compiled source snapshot folder must contain a "${SOURCE_TRACKING_FILE_NAME}" tracking file: ${toDisplayPath(trackingFilePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+      continue;
+    }
+    validateSourceTrackingFile(trackingFilePath, errors);
+  }
+}
+
+function validateSourceTrackingFile(filePath, errors) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split(/\r?\n/);
+
+  if (firstNonEmptyLine(content) !== '# Source') {
+    errors.push(`Source tracking file must start with a "# Source" heading: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+  }
+
+  const timestampRe = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+  for (const field of ['last-fetch-timestamp', 'last-compilation-timestamp']) {
+    const fieldLine = lines.find((line) => line.trim().startsWith(`${field}:`));
+    if (!fieldLine) {
+      errors.push(`Source tracking file must include a "${field}:" line: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+      continue;
+    }
+    const value = fieldLine.trim().slice(`${field}:`.length).trim();
+    if (!timestampRe.test(value)) {
+      errors.push(`Source tracking file "${field}" must match "YYYY-MM-DD HH:MM:SS": ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+    }
+  }
+}
+
 function lintSlideFile(filePath, documentPaths, xdrsRoot, errors) {
   const fileName = path.basename(filePath);
 
@@ -1983,6 +2262,10 @@ function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors, externalSc
       if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)) {
         errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget} [_core-adr-policy-001]`);
       }
+
+      if (isSourceSnapshotPath(link.resolvedPath)) {
+        errors.push(`Document must not link directly to compiled-source snapshot content, which is not authoritative (see _core-adr-policy-019 rule 14) in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget} [_core-adr-policy-019.14-source-not-authoritative]`);
+      }
     }
   }
 }
@@ -2069,6 +2352,11 @@ function shouldValidateResourceLink(rawTarget) {
     || IMAGE_EXTENSIONS.has(extension);
 }
 
+function isSourceSnapshotPath(resolvedPath) {
+  const normalized = normalizePath(resolvedPath).split(path.sep).join('/');
+  return normalized.includes(`/${RESOURCE_DIR_NAME}/${SOURCE_SNAPSHOT_DIR_NAME}/`);
+}
+
 function extractDescriptionText(block) {
   const lines = block.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {