atris 3.34.0 → 3.36.0

package/commands/business-sync.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const path = require('path');
 const { loadManifest, saveManifest } = require('../lib/manifest');
 const { removeBaseContents, writeBaseContents } = require('../lib/company-brain-sync');
+const { collectCloudOrphans } = require('../commands/cloud');
 
 const WATCH_IGNORED_DIRS = new Set([
   '.git', '.atris', '.claude', '.cursor', '.next', '.cache',
@@ -31,6 +32,8 @@ function parseBusinessSyncArgs(args = []) {
   const resolveFlag = parseFlagValue(args, '--resolve', null);
   const resolve = resolveFlag || (resolveIdx !== -1 ? positional[resolveIdx + 1] : null);
   const resolvePath = parseFlagValue(args, '--path', parseFlagValue(args, '--file', null));
+  const takeRaw = parseFlagValue(args, '--take', null);
+  const take = takeRaw ? String(takeRaw).trim().toLowerCase() : null;
   const commandWords = new Set(['status', 'doctor', 'review', 'resolve', 'local', 'cloud', 'both', 'merge']);
   const slug = positional.find((arg) => !commandWords.has(arg)) || null;
   const dryRun = args.includes('--dry-run');
@@ -39,9 +42,10 @@ function parseBusinessSyncArgs(args = []) {
   const watch = args.includes('--watch');
   const intervalSec = Number.parseInt(parseFlagValue(args, '--interval', '60'), 10);
   const debounceSec = Number.parseInt(parseFlagValue(args, '--debounce', '5'), 10);
+  const showOrphans = args.includes('--show-orphans');
   const help = args.includes('--help') || args.includes('-h') || positional[0] === 'help';
 
-  return { slug, dryRun, timeout, allowDelete, watch, intervalSec, debounceSec, status, review, resolve, resolvePath, help };
+  return { slug, dryRun, timeout, allowDelete, watch, intervalSec, debounceSec, status, review, resolve, resolvePath, take, showOrphans, help };
 }
 
 function readBusinessSlug(cwd = process.cwd()) {
@@ -322,6 +326,20 @@ function renderLocalSyncStatus(status) {
   } else {
     lines.push('  warnings: none');
   }
+  if (status.orphanError !== undefined) {
+    lines.push(`  orphans: ${status.orphanError}`);
+  } else if (status.orphanPaths !== undefined) {
+    if (status.orphanPaths.length === 0) {
+      lines.push('  orphans: none');
+    } else {
+      const orphanLabel = status.orphanPaths.length === 1 ? 'file' : 'files';
+      lines.push(`  orphans: ${status.orphanPaths.length} cloud ${orphanLabel} not present locally`);
+      status.orphanPaths.slice(0, 20).forEach((p) => lines.push(`    - ${p.replace(/^\//, '')}`));
+      if (status.orphanPaths.length > 20) {
+        lines.push(`    ... +${status.orphanPaths.length - 20} more`);
+      }
+    }
+  }
   if (status.heartbeat && status.heartbeat.updated_at) {
     lines.push(`  watcher: last heartbeat ${status.heartbeat.updated_at} (${status.heartbeat.state || 'unknown'})`);
   } else {
@@ -334,15 +352,18 @@ function renderLocalSyncStatus(status) {
 
 function renderBusinessSyncHelp() {
   return [
-    'Usage: atris sync [business] [--dry-run] [--watch] [--status] [--review] [--resolve local|cloud|both|merge] [--path <file>] [--timeout 120]',
+    'Usage: atris sync [business] [--dry-run] [--watch] [--status] [--show-orphans] [--review] [--take local|cloud] [--resolve local|cloud|both|merge] [--path <file>] [--timeout 120]',
     '',
     'Safe loop:',
     '  Pull -> Review -> Publish',
     '',
     'Commands:',
     '  atris sync --status       Show local sync health',
+    '  atris sync --status --show-orphans   Show local sync health plus cloud files not present locally',
     '  atris sync --dry-run      Preview pull and publish plans without writing cloud',
-    '  atris sync --review       Read the latest conflict packet',
+    '  atris sync --review       List conflicts; pick local / cloud / merge per file',
+    '  atris sync --review --take local|cloud',
+    '                            Non-interactive: take local or cloud for every conflict',
     '  atris sync --resolve cloud|local|merge [--path <file>]',
     '  atris sync --watch        Keep the workspace live with the same safety gates',
     '',
@@ -353,6 +374,147 @@ function renderBusinessSyncHelp() {
   ].join('\n');
 }
 
+function readTextIfExists(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function buildConflictMarkers(localContent = '', remoteContent = '') {
+  const local = String(localContent);
+  const remote = String(remoteContent);
+  const localBody = local.endsWith('\n') || local === '' ? local : `${local}\n`;
+  const remoteBody = remote.endsWith('\n') || remote === '' ? remote : `${remote}\n`;
+  return `<<<<<<< local\n${localBody}=======\n${remoteBody}>>>>>>> cloud\n`;
+}
+
+function listConflictFiles(entries = []) {
+  const lines = [];
+  const count = entries.length;
+  if (count === 0) {
+    lines.push('no sync conflicts need review.');
+    return `${lines.join('\n')}\n`;
+  }
+  lines.push(`${count} file${count === 1 ? '' : 's'} conflict`);
+  entries.forEach((entry, index) => {
+    lines.push(`  ${index + 1}. ${entry.targetRel}`);
+  });
+  lines.push('');
+  lines.push('pick local / cloud / merge per file (interactive), or run:');
+  lines.push('  atris sync --review --take local');
+  lines.push('  atris sync --review --take cloud');
+  lines.push('merge writes standard conflict markers into the file (no .remote dump).');
+  return `${lines.join('\n')}\n`;
+}
+
+function applyReviewChoice(cwd, entry, choice) {
+  const strategy = String(choice || '').trim().toLowerCase();
+  if (!['local', 'cloud', 'merge'].includes(strategy)) {
+    throw new Error(`unknown choice "${choice}". use local, cloud, or merge.`);
+  }
+
+  const targetPath = assertWorkspaceTarget(cwd, entry.targetRel);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+
+  if (strategy === 'merge') {
+    const localContent = readTextIfExists(entry.localPath);
+    const remoteContent = readTextIfExists(entry.remotePath);
+    fs.writeFileSync(targetPath, buildConflictMarkers(localContent, remoteContent), 'utf8');
+  } else {
+    const sourcePath = strategy === 'local' ? entry.localPath : entry.remotePath;
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`missing ${strategy} artifact for ${entry.targetRel}`);
+    }
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  // Review path never leaves sibling .remote dumps next to workspace files.
+  cleanupResolvedConflictSidecars(cwd, entry.targetRel, { keepCloud: false });
+  cleanupConflictPacketArtifacts(entry);
+  return { path: entry.targetRel, choice: strategy };
+}
+
+async function promptReviewChoice(entry, ask) {
+  const answer = await ask(`${entry.targetRel}: local / cloud / merge? `);
+  const choice = String(answer || '').trim().toLowerCase();
+  if (!['local', 'cloud', 'merge'].includes(choice)) {
+    throw new Error(`invalid choice "${answer}". use local, cloud, or merge.`);
+  }
+  return choice;
+}
+
+/**
+ * S2 conflict handler for `atris sync --review`.
+ * Lists each conflicting file, then resolves via interactive prompt or `--take local|cloud`.
+ * Merge writes standard conflict markers into the target file (no workspace .remote dump).
+ */
+async function runSyncReview(cwd = process.cwd(), options = {}) {
+  const take = options.take ? String(options.take).trim().toLowerCase() : null;
+  if (take && !['local', 'cloud'].includes(take)) {
+    return {
+      resolved: [],
+      choices: [],
+      message: 'use --take local or --take cloud (merge is interactive only).\n',
+      exitCode: 1,
+    };
+  }
+
+  const wantedTarget = normalizeResolvePath(options.path || options.resolvePath || null);
+  const entries = collectConflictResolutionEntries(cwd)
+    .filter((entry) => !wantedTarget || normalizeResolvePath(entry.targetRel) === wantedTarget);
+
+  if (entries.length === 0) {
+    // Fall back to packet summary when no resolvable .local artifacts exist.
+    return {
+      resolved: [],
+      choices: [],
+      message: renderLatestConflictReview(cwd),
+      exitCode: 0,
+    };
+  }
+
+  const lines = [];
+  lines.push(`${entries.length} file${entries.length === 1 ? '' : 's'} conflict`);
+  entries.forEach((entry, index) => {
+    lines.push(`  ${index + 1}. ${entry.targetRel}`);
+  });
+
+  const interactive = typeof options.ask === 'function';
+  if (!take && !interactive) {
+    lines.push('');
+    lines.push('pick local / cloud / merge per file (interactive), or run:');
+    lines.push('  atris sync --review --take local');
+    lines.push('  atris sync --review --take cloud');
+    lines.push('merge writes standard conflict markers into the file (no .remote dump).');
+    lines.push('');
+    lines.push(renderLatestConflictReview(cwd).trimEnd());
+    lines.push('');
+    return { resolved: [], choices: [], message: `${lines.join('\n')}\n`, exitCode: 0 };
+  }
+
+  const choices = [];
+  const resolved = [];
+  for (const entry of entries) {
+    const choice = take || await promptReviewChoice(entry, options.ask);
+    const result = applyReviewChoice(cwd, entry, choice);
+    choices.push(result);
+    resolved.push(result.path);
+    lines.push(`  -> ${result.path}: ${result.choice}`);
+  }
+
+  const finalizedManifests = cleanupEmptyConflictPackets(cwd, entries);
+  lines.push('');
+  lines.push(`resolved ${resolved.length} conflict${resolved.length === 1 ? '' : 's'}.`);
+  if (finalizedManifests.length) {
+    lines.push(`updated sync manifest for ${finalizedManifests.join(', ')}.`);
+  }
+  lines.push('next: run `atris sync --dry-run` before publishing.');
+  lines.push('');
+  return { resolved, choices, message: `${lines.join('\n')}\n`, exitCode: 0 };
+}
+
 function renderLatestConflictReview(cwd = process.cwd()) {
   const summaries = listConflictSummaries(cwd);
   if (summaries.length === 0) {
@@ -782,7 +944,7 @@ async function runSyncCycle(plan, cwd, options = {}) {
   }
 }
 
-async function businessSync(args = process.argv.slice(3), cwd = process.cwd()) {
+async function businessSync(args = process.argv.slice(3), cwd = process.cwd(), deps = {}) {
   const options = resolveBusinessSyncOptions(args, cwd);
 
   if (options.help) {
@@ -791,12 +953,32 @@ async function businessSync(args = process.argv.slice(3), cwd = process.cwd()) {
   }
 
   if (options.status) {
-    process.stdout.write(renderLocalSyncStatus(collectLocalSyncStatus(cwd, options)));
+    const status = collectLocalSyncStatus(cwd, options);
+    if (options.showOrphans) {
+      try {
+        const { orphanPaths } = await collectCloudOrphans(cwd, options.slug, deps);
+        status.orphanPaths = orphanPaths;
+      } catch (err) {
+        status.orphanError = err.message || String(err);
+      }
+    }
+    process.stdout.write(renderLocalSyncStatus(status));
     return;
   }
 
   if (options.review) {
-    process.stdout.write(renderLatestConflictReview(cwd));
+    let ask = null;
+    if (!options.take && process.stdin.isTTY) {
+      const { promptUser } = require('../utils/auth');
+      ask = (question) => promptUser(question);
+    }
+    const result = await runSyncReview(cwd, {
+      take: options.take,
+      path: options.resolvePath,
+      ask,
+    });
+    process.stdout.write(result.message);
+    if (result.exitCode && result.exitCode !== 0) process.exit(result.exitCode);
     return;
   }
 
@@ -894,8 +1076,10 @@ async function businessSync(args = process.argv.slice(3), cwd = process.cwd()) {
 }
 
 module.exports = {
+  applyReviewChoice,
   businessSync,
   buildBusinessSyncPlan,
+  buildConflictMarkers,
   canPreviewPush,
   collectBrainSnapshot,
   collectWorkspaceSnapshot,
@@ -903,6 +1087,7 @@ module.exports = {
   collectLocalSyncStatus,
   collectConflictResolutionEntries,
   describeWatchFailure,
+  listConflictFiles,
   parseBusinessSyncArgs,
   readBusinessSlug,
   renderLatestConflictReview,
@@ -910,6 +1095,7 @@ module.exports = {
   renderBusinessSyncHelp,
   resolveLatestConflict,
   resolveBusinessSyncOptions,
+  runSyncReview,
   safeLineMerge,
   safeMarkdownMerge,
   shouldIgnoreWatchPath,

package/commands/business.js

@@ -28,6 +28,42 @@ function isHelpToken(arg) {
   return arg === '--help' || arg === '-h' || arg === 'help' || arg === '-?';
 }
 
+const BUSINESS_CREATE_USAGE = 'Usage: atris business create <name> [--description "..."] [--workspace] [--here|--root <dir>]';
+
+function isAccidentalHelpBusiness(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return false;
+  if (isHelpToken(raw)) return true;
+  const normalized = slugify(raw);
+  if (normalized === 'help') return true;
+  if (/^help-\d+$/.test(normalized)) return true;
+  return false;
+}
+
+function validateBusinessCreateName(name) {
+  if (!name || !String(name).trim()) {
+    return { ok: false, usage: BUSINESS_CREATE_USAGE };
+  }
+  if (isHelpToken(name)) {
+    return { ok: false, usage: BUSINESS_CREATE_USAGE };
+  }
+  if (String(name).startsWith('-')) {
+    return {
+      ok: false,
+      usage: BUSINESS_CREATE_USAGE,
+      detail: `Refusing to create a business named "${name}" — looks like a flag, not a name.`,
+    };
+  }
+  if (isAccidentalHelpBusiness(name)) {
+    return {
+      ok: false,
+      usage: BUSINESS_CREATE_USAGE,
+      detail: `Refusing to create a business named "${name}" — looks like accidental help output, not a real business.`,
+    };
+  }
+  return { ok: true };
+}
+
 function loadBusinesses() {
   const p = getBusinessConfigPath();
   if (!fs.existsSync(p)) return {};
@@ -308,14 +344,46 @@ function analyzeBusinessDoctor({ cache = {}, cloudBusinesses = [], folderBinding
     }
   }
 
+  const cacheRemovals = [];
+  for (const business of cloudBusinesses || []) {
+    if (!isAccidentalHelpBusiness(business?.name) && !isAccidentalHelpBusiness(business?.slug)) continue;
+    const label = business.slug || business.name || business.id;
+    issues.push({
+      level: 'warn',
+      code: 'accidental-help-business',
+      subject: label,
+      message: `${label} looks like an accidental help business (April 2026 ghost rows)`,
+      fixable: true,
+    });
+  }
+
+  for (const [key, entry] of Object.entries(cache || {})) {
+    const active = findActiveMatch(key, entry);
+    const accidental = isAccidentalHelpBusiness(key)
+      || isAccidentalHelpBusiness(entry?.name)
+      || isAccidentalHelpBusiness(entry?.slug)
+      || (active && (isAccidentalHelpBusiness(active.name) || isAccidentalHelpBusiness(active.slug)));
+    if (!accidental) continue;
+    issues.push({
+      level: 'warn',
+      code: 'accidental-help-cache',
+      subject: key,
+      message: `${key} is cached for an accidental help business`,
+      fixable: true,
+    });
+    if (!cacheRemovals.includes(key)) cacheRemovals.push(key);
+  }
+
   return {
     issues,
     cacheUpdates,
+    cacheRemovals,
     stats: {
       cache_entries: Object.keys(cache || {}).length,
       cloud_active: cloudBusinesses.length,
       folders: folderBindings.length,
       fixable_cache_entries: Object.keys(cacheUpdates).length,
+      accidental_help_cache_removals: cacheRemovals.length,
     },
   };
 }
@@ -2191,11 +2259,20 @@ async function businessDoctor(...args) {
   });
 
   const cacheUpdateKeys = Object.keys(analysis.cacheUpdates);
+  const cacheRemovalKeys = analysis.cacheRemovals || [];
   let fixed = [];
-  if (options.fix && cacheUpdateKeys.length > 0) {
-    cache = { ...cache, ...analysis.cacheUpdates };
+  if (options.fix && (cacheUpdateKeys.length > 0 || cacheRemovalKeys.length > 0)) {
+    if (cacheUpdateKeys.length > 0) {
+      cache = { ...cache, ...analysis.cacheUpdates };
+    }
+    for (const key of cacheRemovalKeys) {
+      delete cache[key];
+      fixed.push(`removed:${key}`);
+    }
+    if (cacheUpdateKeys.length > 0) {
+      fixed.push(...cacheUpdateKeys);
+    }
     saveBusinesses(cache);
-    fixed = cacheUpdateKeys;
     analysis = analyzeBusinessDoctor({
       cache,
       cloudBusinesses: listResult.data,
@@ -2237,11 +2314,10 @@ async function businessDoctor(...args) {
 }
 
 async function createBusinessInternal(name, flags = [], mode = 'auto') {
-  if (!name || isHelpToken(name) || String(name).startsWith('-')) {
-    console.error('Usage: atris business create <name> [--description "..."] [--workspace] [--here|--root <dir>]');
-    if (name && String(name).startsWith('-') && !isHelpToken(name)) {
-      console.error(`\n  Refusing to create a business named "${name}" — looks like a flag, not a name.`);
-    }
+  const validation = validateBusinessCreateName(name);
+  if (!validation.ok) {
+    console.error(validation.usage);
+    if (validation.detail) console.error(`\n  ${validation.detail}`);
     process.exit(1);
   }
 
@@ -2897,6 +2973,11 @@ async function businessCommand(subcommand, ...args) {
     printBusinessHelp();
     return;
   }
+  const nameTakingSubcommands = new Set(['create', 'new', 'init', 'workspace']);
+  if (nameTakingSubcommands.has(subcommand) && args.some(isHelpToken)) {
+    printBusinessHelp();
+    return;
+  }
   if (args.length > 0 && isHelpToken(args[0]) && subcommand !== 'doctor') {
     printBusinessHelp();
     return;
@@ -2999,6 +3080,8 @@ module.exports = {
   saveBusinesses,
   getBusinessConfigPath,
   businessMatchesSlug,
+  isAccidentalHelpBusiness,
+  validateBusinessCreateName,
   analyzeBusinessDoctor,
   readBusinessFolderBindings,
   createCanonicalBusinessWorkspace,

package/commands/clean.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const escapeRegExp = require('../lib/escape-regexp');
 
@@ -250,7 +251,7 @@ function findStaleTasks(atrisDir) {
  * Detects both out-of-bounds AND drift (symbol moved to different line)
  * Returns { healed: number, unhealable: array }
  */
-function healBrokenMapRefs(cwd, atrisDir, dryRun = false) {
+function healBrokenMapRefs(cwd, atrisDir, dryRun = false, homeDir = os.homedir()) {
   const mapFile = path.join(atrisDir, 'MAP.md');
   if (!fs.existsSync(mapFile)) return { healed: 0, unhealable: [] };
 
@@ -261,12 +262,12 @@ function healBrokenMapRefs(cwd, atrisDir, dryRun = false) {
   // Match both `file.js:123` and `file.js:123-456` with surrounding context
   // [^\S\n] = horizontal whitespace only (no newlines)
   // Required delimiter [(,[,—,-] prevents bleeding into adjacent refs on same line
-  const refPattern = /(`?)([a-zA-Z0-9_\-./\\]+\.(js|ts|py|go|rs|rb|java|c|cpp|h|hpp|md|json|yaml|yml)):(\d+)(?:-(\d+))?(`?)([^\S\n]*[\(\[—\-][^\S\n]*([^)\]\n]+))?/g;
+  const refPattern = /(`?)([a-zA-Z0-9_~\-./\\]+\.(js|ts|py|go|rs|rb|java|c|cpp|h|hpp|md|json|yaml|yml)):(\d+)(?:-(\d+))?(`?)([^\S\n]*[\(\[—\-][^\S\n]*([^)\]\n]+))?/g;
 
   // Function Inventory form: `symbolName()` → `file:line[-line]`
   // Pre-scan to build a (file:line) → symbol map so refs with the symbol BEFORE them still verify.
   const preRefSymbols = {};
-  const preRefPattern = /`([a-zA-Z_][a-zA-Z0-9_]*)\s*\(?\s*\)?`\s*(?:→|->)\s*`([a-zA-Z0-9_\-./\\]+\.(?:js|ts|py|go|rs|rb|java|c|cpp|h|hpp|md|json|yaml|yml)):(\d+)(?:-\d+)?`/g;
+  const preRefPattern = /`([a-zA-Z_][a-zA-Z0-9_]*)\s*\(?\s*\)?`\s*(?:→|->)\s*`([a-zA-Z0-9_~\-./\\]+\.(?:js|ts|py|go|rs|rb|java|c|cpp|h|hpp|md|json|yaml|yml)):(\d+)(?:-\d+)?`/g;
   let preMatch;
   while ((preMatch = preRefPattern.exec(mapContent)) !== null) {
     preRefSymbols[`${preMatch[2]}:${preMatch[3]}`] = preMatch[1];
@@ -276,7 +277,10 @@ function healBrokenMapRefs(cwd, atrisDir, dryRun = false) {
   const fileCache = {};
   function readFileCached(filePath) {
     if (!fileCache[filePath]) {
-      const fullPath = path.join(cwd, filePath);
+      const expandedPath = filePath.startsWith('~/') || filePath.startsWith('~\\')
+        ? path.join(homeDir, filePath.slice(2))
+        : filePath;
+      const fullPath = path.isAbsolute(expandedPath) ? expandedPath : path.join(cwd, expandedPath);
       if (!fs.existsSync(fullPath)) return null;
       try {
         const content = fs.readFileSync(fullPath, 'utf8');
@@ -320,7 +324,15 @@ function healBrokenMapRefs(cwd, atrisDir, dryRun = false) {
     // Find where the symbol actually is now
     const newStart = findSymbolLine(file.content, symbol);
     if (!newStart) {
-      unhealable.push({ file: filePath, line: startLine, reason: `Symbol "${symbol}" not found` });
+      // A "symbol" that appears nowhere in the file is often descriptive
+      // prose from the annotation ("PATCH /api/...", "mission drain"), not
+      // a code identifier. Suppress those for in-bounds refs to existing
+      // files; still flag out-of-bounds refs and vanished identifiers
+      // (camelCase/snake_case words were plausibly real symbols).
+      const identifierLike = /[a-z][^\s]*[A-Z]|_/.test(symbol);
+      if (outOfBounds || identifierLike) {
+        unhealable.push({ file: filePath, line: startLine, reason: `Symbol "${symbol}" not found` });
+      }
       continue;
     }
 
@@ -404,28 +416,30 @@ function findFunctionEnd(lines, startLine) {
 function extractSymbol(context) {
   if (!context) return null;
 
-  // Clean up the context
-  const cleaned = context.trim()
-    .replace(/`/g, '')                // Strip backticks
-    .replace(/^[\(\[—\-:]+\s*/, '')  // Remove leading punctuation
-    .replace(/[\)\]]+$/, '')          // Remove trailing brackets
+  const original = context;
+
+  // Clean up the context without stripping parentheses from a symbol ending in ().
+  const unquoted = context.trim().replace(/`/g, '');
+  const wrapper = unquoted.match(/^([\(\[])/)?.[1];
+  let cleaned = unquoted
+    .replace(/^[\(\[—\-:]+\s*/, '')
     .trim();
+  if (wrapper === '(') cleaned = cleaned.replace(/\)$/, '').trim();
+  if (wrapper === '[') cleaned = cleaned.replace(/\]$/, '').trim();
 
   if (!cleaned) return null;
 
-  // Try to extract a function/class/variable name
-  // Pattern: word that looks like an identifier
-  const identifierMatch = cleaned.match(/\b([a-zA-Z_][a-zA-Z0-9_]*(?:Atris|Entry|Handler|Cmd|Function|Class)?)\b/i);
+  const tokenMatch = cleaned.match(/^([a-zA-Z_][a-zA-Z0-9_]*)(\(\))?/);
+  if (!tokenMatch) return null;
 
-  if (identifierMatch) {
-    return identifierMatch[1];
-  }
+  const symbol = tokenMatch[1];
+  const token = tokenMatch[0];
+  const codeShaped = symbol.includes('_') || /[a-z][A-Z]/.test(symbol) || token.endsWith('()');
+  if (codeShaped) return symbol;
 
-  // Fallback: first word
-  const firstWord = cleaned.split(/\s+/)[0];
-  if (firstWord && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(firstWord)) {
-    return firstWord;
-  }
+  const isSingleWord = cleaned === symbol;
+  const isBackticked = original.includes(`\`${symbol}\``);
+  if (isSingleWord && isBackticked) return symbol;
 
   return null;
 }
@@ -445,7 +459,7 @@ function findSymbolLine(fileContent, symbol) {
     new RegExp(`^\\s*class\\s+${esc}\\b`),                      // class name
     new RegExp(`^\\s*${esc}\\s*[:(]`),                           // name: or name(
     new RegExp(`exports\\.${esc}\\s*=`),                         // exports.name =
-    new RegExp(`^\\s*def\\s+${esc}\\s*\\(`),                     // def name( (Python)
+    new RegExp(`^\\s*(async\\s+)?def\\s+${esc}\\s*\\(`),           // [async] def name( (Python)
   ];
 
   for (const pattern of patterns) {
@@ -465,15 +479,27 @@ function findSymbolLine(fileContent, symbol) {
  */
 function findStalePages(cwd, atrisDir) {
   const stalePages = [];
+  const skippedDirs = new Set(['archive', 'runs', 'qa', 'node_modules', '.git']);
+  const currentYear = new Date().getFullYear();
+
+  function shouldSkipDir(dir, name) {
+    if (skippedDirs.has(name)) return true;
+    if (/^\d{4}$/.test(name) && path.basename(path.dirname(dir)) === 'logs') {
+      return Number(name) < currentYear;
+    }
+    return false;
+  }
 
   function scanDir(dir) {
     if (!fs.existsSync(dir)) return;
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory() && entry.name !== 'archive' && entry.name !== 'node_modules') {
+      if (entry.isDirectory()) {
+        if (shouldSkipDir(fullPath, entry.name)) continue;
         scanDir(fullPath);
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      } else if (entry.isFile()) {
+        if (!entry.name.endsWith('.md')) continue;
         const result = checkPageStaleness(cwd, fullPath);
         if (result) stalePages.push(result);
       }