hive-lite 0.1.0

package/src/lib/health.js

@@ -0,0 +1,1012 @@
+const fs = require('fs');
+const path = require('path');
+const { createId } = require('./id');
+const { exists, readText } = require('./fsx');
+const { tryGit } = require('./git');
+const { matchesPattern } = require('./glob');
+const { hiveDir, mapFile } = require('./map');
+const { normalizeAreaScope } = require('./scope');
+const { parseYaml } = require('./yaml');
+const {
+  ROLE_TAXONOMY,
+  isCanonicalRole,
+  isInternalBehaviorRole,
+  isKnownRole,
+  isUiManualRole,
+  normalizeRole,
+} = require('./roles');
+
+const GENERIC_AREA_IDS = new Set([
+  'dashboard',
+  'frontend',
+  'backend',
+  'server',
+  'client',
+  'components',
+  'src',
+  'app',
+  'web',
+  'ui',
+  'api',
+  'database',
+  'db',
+  'common',
+  'shared',
+  'utils',
+  'lib',
+]);
+
+const GENERIC_ALIASES = new Set([
+  ...GENERIC_AREA_IDS,
+  'front end',
+  'back end',
+]);
+
+const BUILT_IN_MANUAL_PROFILES = new Set([
+  'manual-verification',
+  'generic-ui-visual',
+  'generic-cli-behavior',
+  'generic-doc-review',
+]);
+
+function normalizePath(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function patternFrom(value) {
+  if (!value) return '';
+  if (typeof value === 'string') return normalizePath(value.trim());
+  return normalizePath((value.pattern || value.path || '').trim());
+}
+
+function readYamlHealth(root, name, fallback, findings) {
+  const file = mapFile(root, name);
+  if (!exists(file)) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'MAP_FILE_MISSING',
+      file: `.hive/map/${name}`,
+      field: '',
+      message: `.hive/map/${name} is missing.`,
+      impact: 'Hive Lite cannot evaluate Project Map health.',
+      fix: 'Run hive-lite init or restore the missing map file.',
+    });
+    return { doc: fallback, valid: false };
+  }
+  try {
+    return { doc: parseYaml(readText(file)), valid: true };
+  } catch (error) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'INVALID_YAML',
+      file: `.hive/map/${name}`,
+      field: '',
+      message: `Could not parse .hive/map/${name}: ${error.message}`,
+      impact: 'Hive Lite cannot safely read the Project Map.',
+      fix: 'Fix the YAML syntax, then rerun hive-lite map health.',
+    });
+    return { doc: fallback, valid: false };
+  }
+}
+
+function validateMapFilesNotIgnored(root, findings) {
+  const files = [
+    '.hive/config.yaml',
+    '.hive/map/project.yaml',
+    '.hive/map/areas.yaml',
+    '.hive/map/rules.yaml',
+    '.hive/map/validation.yaml',
+  ];
+  const output = tryGit(['check-ignore', '--no-index', ...files], { cwd: root });
+  if (!output) return;
+  for (const ignored of output.split(/\r?\n/).filter(Boolean)) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'MAP_FILE_IGNORED',
+      file: ignored,
+      field: '',
+      message: `${ignored} is ignored by git ignore/exclude rules.`,
+      impact: 'Project Map changes may not appear in git status and may not be committed for future agents.',
+      fix: 'Do not ignore `.hive/map/**` or `.hive/config.yaml`; ignore only runtime evidence such as `.hive/context/`, `.hive/changes/`, `.hive/patches/`, and `.hive/state/`.',
+    });
+  }
+}
+
+function trackedFiles(root) {
+  return tryGit(['ls-files'], { cwd: root }).split(/\r?\n/).filter(Boolean).map(normalizePath);
+}
+
+function packageScripts(root) {
+  const file = path.join(root, 'package.json');
+  if (!exists(file)) return {};
+  try {
+    return JSON.parse(readText(file)).scripts || {};
+  } catch {
+    return {};
+  }
+}
+
+function countMatches(files, pattern) {
+  return files.filter((file) => matchesPattern(file, pattern)).length;
+}
+
+function exactPathStatus(root, pattern) {
+  if (pattern.includes('*')) return { exists: true, isDirectory: false };
+  const full = path.join(root, pattern);
+  if (!fs.existsSync(full)) return { exists: false, isDirectory: false };
+  return { exists: true, isDirectory: fs.statSync(full).isDirectory() };
+}
+
+function looksLikeFile(pattern) {
+  if (pattern.includes('*')) return false;
+  return /\.[A-Za-z0-9]+$/.test(path.basename(pattern));
+}
+
+function isBroadWritablePattern(pattern, matchCount) {
+  const normalized = normalizePath(pattern);
+  if (!normalized || normalized === '.' || normalized === './') return true;
+  if (normalized.includes('**')) return true;
+  if (normalized.endsWith('/*')) return matchCount == null || matchCount > 12;
+  if (!normalized.includes('*') && !looksLikeFile(normalized)) return matchCount == null || matchCount > 8;
+  return matchCount > 30;
+}
+
+function field(areaId, suffix) {
+  return `areas[${areaId}]${suffix ? `.${suffix}` : ''}`;
+}
+
+function addFinding(findings, data) {
+  findings.push({
+    id: createId('finding'),
+    severity: data.severity,
+    code: data.code,
+    areaId: data.areaId || null,
+    file: data.file || '.hive/map/areas.yaml',
+    field: data.field || '',
+    message: data.message,
+    impact: data.impact || '',
+    fix: data.fix || '',
+    metrics: data.metrics || undefined,
+    relatedCommand: data.relatedCommand || null,
+  });
+}
+
+function focusForArea(area) {
+  return String(area.name || area.id || '').replace(/[_\.]+/g, ' ').trim();
+}
+
+function mapPromptCommand(area) {
+  const focus = focusForArea(area);
+  return `hive-lite map prompt --focus ${JSON.stringify(focus)} --max-areas 3`;
+}
+
+function isGenericAreaId(id) {
+  const normalized = String(id || '').toLowerCase();
+  if (!normalized.includes('.')) return true;
+  const last = normalized.split('.').pop();
+  return GENERIC_AREA_IDS.has(normalized) || GENERIC_AREA_IDS.has(last);
+}
+
+function validateAreaId(area, areaIds, findings) {
+  if (!area.id) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'MISSING_AREA_ID',
+      field: 'areas[].id',
+      message: 'Area is missing id.',
+      impact: 'Hive Lite cannot route intents to this area.',
+      fix: 'Add a stable area id such as dashboard.action_inbox.',
+    });
+    return;
+  }
+  if (areaIds.has(area.id)) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'DUPLICATE_AREA_ID',
+      areaId: area.id,
+      field: field(area.id, 'id'),
+      message: `Duplicate area id: ${area.id}.`,
+      impact: 'find/check cannot unambiguously refer to this area.',
+      fix: 'Rename or merge duplicate areas.',
+    });
+  }
+  areaIds.add(area.id);
+  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(area.id)) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'GENERIC_AREA_ID',
+      areaId: area.id,
+      field: field(area.id, 'id'),
+      message: `Area id "${area.id}" should be a product/work area id with at least two segments.`,
+      impact: 'find may route to a broad technical area instead of a precise work area.',
+      fix: 'Prefer ids such as dashboard.action_inbox or change.acceptance_flow.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  } else if (isGenericAreaId(area.id)) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'GENERIC_AREA_ID',
+      areaId: area.id,
+      field: field(area.id, 'id'),
+      message: `Area id "${area.id}" is generic.`,
+      impact: 'Generic areas often produce broad Context Packets.',
+      fix: 'Prefer product/work areas rather than parent modules.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+}
+
+function validateFindTerms(area, aliasOwners, findings) {
+  const aliases = (area.aliases || []).filter(Boolean);
+  const concepts = (area.concepts || []).filter(Boolean);
+  const userIntents = (area.user_intents || area.userIntents || []).filter(Boolean);
+
+  if (aliases.length === 0 && concepts.length === 0 && userIntents.length === 0) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'MISSING_FIND_TERMS',
+      areaId: area.id,
+      field: field(area.id, 'aliases'),
+      message: 'Area has no aliases, concepts, or user_intents.',
+      impact: 'find has almost no deterministic signal to match this area.',
+      fix: 'Add user-facing aliases, concepts, or user_intents.',
+      relatedCommand: mapPromptCommand(area),
+    });
+    return;
+  }
+  if (aliases.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'MISSING_ALIASES',
+      areaId: area.id,
+      field: field(area.id, 'aliases'),
+      message: 'Area aliases are empty.',
+      impact: 'find may depend on weak token or grep matches.',
+      fix: 'Add 2-6 phrases users naturally say for this area.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+  if (concepts.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'MISSING_CONCEPTS',
+      areaId: area.id,
+      field: field(area.id, 'concepts'),
+      message: 'Area concepts are empty.',
+      impact: 'find has fewer stable semantic keywords to route intents.',
+      fix: 'Add product/workflow concepts for this area.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+  if (aliases.length > 0 && aliases.every((alias) => GENERIC_ALIASES.has(String(alias).toLowerCase()))) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'GENERIC_ALIASES_ONLY',
+      areaId: area.id,
+      field: field(area.id, 'aliases'),
+      message: 'Area aliases are all generic.',
+      impact: 'find may choose this area for unrelated intents.',
+      fix: 'Add product-specific aliases.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+  for (const alias of aliases) {
+    const key = String(alias).toLowerCase();
+    const owners = aliasOwners.get(key) || [];
+    if (owners.length > 1) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'DUPLICATE_ALIAS',
+        areaId: area.id,
+        field: field(area.id, 'aliases'),
+        message: `Alias "${alias}" also appears in ${owners.filter((id) => id !== area.id).join(', ')}.`,
+        impact: 'find may choose the wrong area when this phrase appears.',
+        fix: 'Keep shared parent terms in concepts and make aliases more specific.',
+      });
+    }
+  }
+}
+
+function validateEntryPoints(root, area, findings) {
+  const entrypoints = area.entrypoints || [];
+  const writableDirect = normalizeAreaScope(root, area).writableDirect || [];
+  if (entrypoints.length === 0) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'MISSING_ENTRYPOINTS',
+      areaId: area.id,
+      field: field(area.id, 'entrypoints'),
+      message: 'Area has no entrypoints.',
+      impact: 'find may rely on grep-only context instead of durable map evidence.',
+      fix: 'Add 1-6 real files an agent should inspect first.',
+      relatedCommand: mapPromptCommand(area),
+    });
+    return;
+  }
+
+  let existing = 0;
+  for (let index = 0; index < entrypoints.length; index += 1) {
+    const entry = entrypoints[index];
+    const entryPath = patternFrom(entry);
+    if (!entryPath) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'ENTRYPOINT_NOT_FOUND',
+        areaId: area.id,
+        field: field(area.id, `entrypoints[${index}].path`),
+        message: 'Entrypoint is missing path.',
+        impact: 'find cannot use this entrypoint.',
+        fix: 'Add a real file path or remove this entrypoint.',
+      });
+      continue;
+    }
+    if (!entry.role) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'ENTRYPOINT_ROLE_MISSING',
+        areaId: area.id,
+        field: field(area.id, `entrypoints[${index}].role`),
+        message: `Entrypoint is missing role: ${entryPath}.`,
+        impact: 'check has less deterministic evidence-policy signal for changed files.',
+        fix: `Set role to one of: ${ROLE_TAXONOMY.join(', ')}.`,
+        relatedCommand: mapPromptCommand(area),
+      });
+    } else if (!isKnownRole(entry.role)) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'UNKNOWN_ROLE_VALUE',
+        areaId: area.id,
+        field: field(area.id, `entrypoints[${index}].role`),
+        message: `Entrypoint role is not supported: ${entry.role}.`,
+        impact: 'check cannot reliably decide whether this change needs manual verification, focused tests, or review.',
+        fix: `Use one of the allowed roles: ${ROLE_TAXONOMY.join(', ')}.`,
+      });
+    } else {
+      const canonical = normalizeRole(entry.role);
+      if (!isCanonicalRole(entry.role)) {
+        addFinding(findings, {
+          severity: 'info',
+          code: 'NON_CANONICAL_ROLE_VALUE',
+          areaId: area.id,
+          field: field(area.id, `entrypoints[${index}].role`),
+          message: `Entrypoint role "${entry.role}" is accepted as "${canonical}".`,
+          impact: 'Future map drafts should use canonical role names.',
+          fix: `Replace "${entry.role}" with "${canonical}" when you next edit this area.`,
+        });
+      }
+      if (canonical === 'unknown' && writableDirect.includes(entryPath)) {
+        addFinding(findings, {
+          severity: 'warning',
+          code: 'ENTRYPOINT_ROLE_UNKNOWN_IN_WRITABLE_DIRECT',
+          areaId: area.id,
+          field: field(area.id, `entrypoints[${index}].role`),
+          message: `Writable direct entrypoint has unknown role: ${entryPath}.`,
+          impact: 'check will require conservative review instead of a precise evidence policy.',
+          fix: 'Assign a specific role if this file has durable behavior in the area.',
+          relatedCommand: mapPromptCommand(area),
+        });
+      }
+    }
+    const full = path.join(root, entryPath);
+    if (!fs.existsSync(full)) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'ENTRYPOINT_NOT_FOUND',
+        areaId: area.id,
+        field: field(area.id, `entrypoints[${index}].path`),
+        message: `Entrypoint does not exist: ${entryPath}.`,
+        impact: 'find may route to stale files.',
+        fix: 'Update the path or remove the stale entrypoint.',
+        relatedCommand: mapPromptCommand(area),
+      });
+      continue;
+    }
+    if (fs.statSync(full).isDirectory()) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'ENTRYPOINT_IS_DIRECTORY',
+        areaId: area.id,
+        field: field(area.id, `entrypoints[${index}].path`),
+        message: `Entrypoint is a directory: ${entryPath}.`,
+        impact: 'entrypoints should point to files an agent can inspect first.',
+        fix: 'Replace this with specific files.',
+      });
+      continue;
+    }
+    existing += 1;
+  }
+
+  if (existing === 0) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'ENTRYPOINTS_ALL_MISSING',
+      areaId: area.id,
+      field: field(area.id, 'entrypoints'),
+      message: 'All entrypoints are missing or unusable.',
+      impact: 'find cannot produce a reliable map-backed Context Packet.',
+      fix: 'Refresh entrypoint paths from current repo files.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+}
+
+function rawScope(area) {
+  const scope = area.scope || {};
+  return {
+    direct: scope.writable_direct || (!area.scope ? area.writable_scope || [] : []),
+    conditional: scope.writable_conditional || [],
+    broad: scope.writable_broad_fallback || [],
+    forbidden: scope.forbidden || area.do_not_touch || [],
+  };
+}
+
+function validateWritableScope(root, tracked, area, findings) {
+  const normalized = normalizeAreaScope(root, area);
+  const raw = rawScope(area);
+
+  if (normalized.writableDirect.length === 0) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'MISSING_WRITABLE_DIRECT',
+      areaId: area.id,
+      field: field(area.id, 'scope.writable_direct'),
+      message: 'scope.writable_direct is missing or empty.',
+      impact: 'find cannot safely produce a precise edit_context for this area.',
+      fix: 'Add 2-8 exact writable files.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+
+  if (normalized.writableDirect.length === 0 && normalized.writableBroadFallback.length > 0) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'ONLY_BROAD_FALLBACK',
+      areaId: area.id,
+      field: field(area.id, 'scope.writable_broad_fallback'),
+      message: 'Area only has broad writable fallback scope.',
+      impact: 'find should downgrade this area to discovery_context until direct files are mapped.',
+      fix: 'Keep broad patterns as fallback, but add narrow writable_direct files.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+
+  for (const value of raw.direct) {
+    const pattern = patternFrom(value);
+    if (!pattern) continue;
+    const count = countMatches(tracked, pattern);
+    const status = exactPathStatus(root, pattern);
+    if (isBroadWritablePattern(pattern, count)) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'BROAD_WRITABLE_DIRECT',
+        areaId: area.id,
+        field: field(area.id, area.scope ? 'scope.writable_direct' : 'writable_scope'),
+        message: `Writable direct scope is too broad: ${pattern}.`,
+        impact: 'This can make find issue an unsafe edit permit.',
+        fix: 'Move broad patterns to writable_broad_fallback with requires_review: true, and add exact writable_direct files.',
+        metrics: { matchedGitFiles: count },
+        relatedCommand: mapPromptCommand(area),
+      });
+    } else if (count > 30) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'WRITABLE_DIRECT_MATCHES_TOO_MANY',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_direct'),
+        message: `Writable direct pattern ${pattern} matches ${count} tracked files.`,
+        impact: 'Direct writable scope is too large for a safe edit_context.',
+        fix: 'Replace this with exact files or smaller patterns.',
+        metrics: { matchedGitFiles: count, threshold: 30 },
+      });
+    } else if (count > 12) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'WRITABLE_DIRECT_MATCHES_TOO_MANY',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_direct'),
+        message: `Writable direct pattern ${pattern} matches ${count} tracked files.`,
+        impact: 'Large direct scope reduces the value of check.',
+        fix: 'Prefer 2-8 exact writable files.',
+        metrics: { matchedGitFiles: count, threshold: 12 },
+      });
+    }
+    if (!pattern.includes('*') && !status.exists) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'WRITABLE_DIRECT_NOT_FOUND',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_direct'),
+        message: `Writable direct path does not exist: ${pattern}.`,
+        impact: 'find may authorize edits to stale paths.',
+        fix: 'Update or remove this writable_direct path.',
+        relatedCommand: mapPromptCommand(area),
+      });
+    } else if (status.isDirectory) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'BROAD_WRITABLE_DIRECT',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_direct'),
+        message: `Writable direct path is a directory: ${pattern}.`,
+        impact: 'Direct writable should usually be exact files.',
+        fix: 'Replace this directory with exact writable files.',
+      });
+    }
+  }
+
+  for (const value of raw.broad) {
+    const pattern = patternFrom(value);
+    if (!pattern) continue;
+    const requiresReview = value && typeof value === 'object' ? value.requires_review === true || value.requiresReview === true : false;
+    if (!value.reason) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'BROAD_FALLBACK_MISSING_REASON',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_broad_fallback'),
+        message: `Broad fallback scope is missing reason: ${pattern}.`,
+        impact: 'Humans and agents cannot tell when this fallback is appropriate.',
+        fix: 'Add a reason explaining when this fallback may be used.',
+      });
+    }
+    if (!requiresReview) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'BROAD_FALLBACK_REQUIRES_REVIEW_FALSE',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_broad_fallback'),
+        message: `Broad fallback should require review: ${pattern}.`,
+        impact: 'Broad fallback edits should not be accepted as ordinary clean scope.',
+        fix: 'Set requires_review: true.',
+      });
+    }
+  }
+
+  for (const value of raw.conditional) {
+    const pattern = patternFrom(value);
+    if (!pattern) continue;
+    const requiresReview = value && typeof value === 'object' ? value.requires_review === true || value.requiresReview === true : false;
+    if (!value.reason) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'CONDITIONAL_SCOPE_MISSING_REASON',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_conditional'),
+        message: `Conditional writable scope is missing reason: ${pattern}.`,
+        impact: 'check may require review without explaining why.',
+        fix: 'Add a reason that describes when this scope is valid.',
+      });
+    }
+    if (!requiresReview) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'CONDITIONAL_SCOPE_REQUIRES_REVIEW_FALSE',
+        areaId: area.id,
+        field: field(area.id, 'scope.writable_conditional'),
+        message: `Conditional writable scope should require review: ${pattern}.`,
+        impact: 'Conditional edits should be visible to the human reviewer.',
+        fix: 'Set requires_review: true.',
+      });
+    }
+  }
+
+  if (normalized.forbidden.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'FORBIDDEN_EMPTY',
+      areaId: area.id,
+      field: field(area.id, 'scope.forbidden'),
+      message: 'Area forbidden scope is empty.',
+      impact: 'The Context Packet lacks explicit do-not-touch boundaries.',
+      fix: 'Add local forbidden paths or rely on strong global rules.',
+    });
+  }
+
+  const writablePatterns = [
+    ...normalized.writableDirect,
+    ...normalized.writableConditional.map(patternFrom),
+    ...normalized.writableBroadFallback.map(patternFrom),
+  ].filter(Boolean);
+  for (const writable of writablePatterns) {
+    for (const forbidden of normalized.forbidden) {
+      const overlap = tracked.filter((file) => matchesPattern(file, writable) && matchesPattern(file, forbidden)).slice(0, 3);
+      if (overlap.length > 0) {
+        addFinding(findings, {
+          severity: 'critical',
+          code: 'WRITABLE_FORBIDDEN_CONFLICT',
+          areaId: area.id,
+          field: field(area.id, 'scope'),
+          message: `Writable scope ${writable} overlaps forbidden scope ${forbidden}.`,
+          impact: 'find/check may disagree about whether edits are allowed.',
+          fix: 'Remove the overlap or move the path into conditional scope with review.',
+          metrics: { sample: overlap },
+        });
+      }
+    }
+  }
+}
+
+function commandScript(command) {
+  const text = String(command || '').trim();
+  let match = text.match(/\b(?:npm|pnpm|bun)\s+run\s+([A-Za-z0-9:_-]+)/);
+  if (match) return match[1];
+  match = text.match(/\byarn\s+([A-Za-z0-9:_-]+)/);
+  if (match && match[1] !== 'run') return match[1];
+  if (/\b--filter\b/.test(text)) return null;
+  match = text.match(/\bpnpm\s+([A-Za-z0-9:_-]+)/);
+  if (match && !['exec', 'dlx', 'install', 'add'].includes(match[1])) return match[1];
+  return null;
+}
+
+function profileEvidenceType(profile) {
+  return profile.evidence_type || profile.evidenceType || '';
+}
+
+function profileCoversRoles(profile) {
+  return profile.covers_roles || profile.coversRoles || [];
+}
+
+function validateValidation(area, profilesById, scripts, findings) {
+  const profileIds = (((area.validation || {}).profiles) || []).filter(Boolean);
+  if (profileIds.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'MISSING_VALIDATION',
+      areaId: area.id,
+      field: field(area.id, 'validation.profiles'),
+      message: 'Area has no validation profiles.',
+      impact: 'find may produce a Context Packet without a validation plan.',
+      fix: 'Add a validation profile or project default validation command.',
+    });
+    return;
+  }
+  for (const profileId of profileIds) {
+    const profile = profilesById.get(profileId);
+    if (!profile) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'VALIDATION_PROFILE_NOT_FOUND',
+        areaId: area.id,
+        file: '.hive/map/validation.yaml',
+        field: field(area.id, 'validation.profiles'),
+        message: `Validation profile not found: ${profileId}.`,
+        impact: 'hive validate cannot run the profile referenced by this area.',
+        fix: 'Add the profile to validation.yaml or remove the reference.',
+      });
+      continue;
+    }
+    const hasManual = profile.type === 'manual' || (profile.instructions || []).length > 0;
+    const evidenceType = profileEvidenceType(profile);
+    const coversRoles = profileCoversRoles(profile);
+    if (!profile.command && !hasManual) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'VALIDATION_PROFILE_EMPTY',
+        areaId: area.id,
+        file: '.hive/map/validation.yaml',
+        field: `profiles[${profileId}]`,
+        message: `Validation profile ${profileId} has no command or manual instructions.`,
+        impact: 'hive validate cannot collect useful evidence for this profile.',
+        fix: 'Add a command or mark it as manual with instructions.',
+      });
+    }
+    if (!evidenceType) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'VALIDATION_PROFILE_MISSING_EVIDENCE_TYPE',
+        areaId: area.id,
+        file: '.hive/map/validation.yaml',
+        field: `profiles[${profileId}].evidence_type`,
+        message: `Validation profile ${profileId} is missing evidence_type.`,
+        impact: 'check has less signal about whether this profile proves build, test, manual, or review evidence.',
+        fix: 'Add evidence_type such as build, typecheck, existing_tests, focused_test, manual_visual, or manual_cli.',
+      });
+    }
+    if (!Array.isArray(coversRoles) || coversRoles.length === 0) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'VALIDATION_PROFILE_MISSING_COVERS_ROLES',
+        areaId: area.id,
+        file: '.hive/map/validation.yaml',
+        field: `profiles[${profileId}].covers_roles`,
+        message: `Validation profile ${profileId} is missing covers_roles.`,
+        impact: 'check cannot tell which changed roles this validation meaningfully covers.',
+        fix: `Add covers_roles using allowed roles: ${ROLE_TAXONOMY.join(', ')}.`,
+      });
+    } else {
+      for (const role of coversRoles) {
+        if (!isKnownRole(role)) {
+          addFinding(findings, {
+            severity: 'critical',
+            code: 'UNKNOWN_ROLE_VALUE',
+            areaId: area.id,
+            file: '.hive/map/validation.yaml',
+            field: `profiles[${profileId}].covers_roles`,
+            message: `Validation profile ${profileId} covers unsupported role: ${role}.`,
+            impact: 'Evidence coverage cannot be evaluated deterministically.',
+            fix: `Use one of the allowed roles: ${ROLE_TAXONOMY.join(', ')}.`,
+          });
+        }
+      }
+    }
+    const script = commandScript(profile.command);
+    if (script && Object.keys(scripts).length > 0 && !scripts[script]) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'VALIDATION_COMMAND_SCRIPT_NOT_FOUND',
+        areaId: area.id,
+        file: '.hive/map/validation.yaml',
+        field: `profiles[${profileId}].command`,
+        message: `Validation command references package script "${script}", but root package.json does not define it.`,
+        impact: 'hive validate may fail or require a custom command.',
+        fix: 'Update validation.yaml or add the missing package script.',
+      });
+    }
+  }
+}
+
+function areaRoles(area) {
+  return (area.entrypoints || [])
+    .map((entry) => normalizeRole(entry.role))
+    .filter(Boolean);
+}
+
+function validateVerification(area, profilesById, findings) {
+  const verification = area.verification || {};
+  const roles = areaRoles(area);
+  const hasUiRole = roles.some((role) => isUiManualRole(role));
+  const internalRoles = roles.filter((role) => isInternalBehaviorRole(role));
+  const focusedRecommended = verification.focused_test_recommended_for_roles || verification.focusedTestRecommendedForRoles || [];
+  const focusedRequired = verification.focused_test_required_for_roles || verification.focusedTestRequiredForRoles || [];
+  const focusedPolicy = [...focusedRecommended, ...focusedRequired].map((role) => normalizeRole(role)).filter(Boolean);
+  const validationProfiles = (((area.validation || {}).profiles) || []).filter(Boolean);
+  const manualProfiles = verification.manual_profiles || verification.manualProfiles || [];
+
+  for (const role of [...focusedRecommended, ...focusedRequired]) {
+    if (!isKnownRole(role)) {
+      addFinding(findings, {
+        severity: 'critical',
+        code: 'UNKNOWN_ROLE_VALUE',
+        areaId: area.id,
+        field: field(area.id, 'verification'),
+        message: `Verification policy references unsupported role: ${role}.`,
+        impact: 'check cannot reliably apply the evidence policy.',
+        fix: `Use one of the allowed roles: ${ROLE_TAXONOMY.join(', ')}.`,
+      });
+    }
+  }
+
+  if (hasUiRole && verification.direct_manual_allowed !== true && manualProfiles.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'UI_ROLE_WITHOUT_MANUAL_VERIFICATION',
+      areaId: area.id,
+      field: field(area.id, 'verification.manual_profiles'),
+      message: 'UI-facing area has no manual verification fallback.',
+      impact: 'check may not clearly ask for human-visible evidence after UI changes.',
+      fix: 'Set verification.direct_manual_allowed: true and add a generic manual profile such as manual-verification.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+
+  if (internalRoles.length > 0 && focusedPolicy.length === 0 && verification.review_with_reason_allowed !== true && validationProfiles.length === 0) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'INTERNAL_ROLE_WITHOUT_VERIFICATION_POLICY',
+      areaId: area.id,
+      field: field(area.id, 'verification'),
+      message: `Internal roles lack focused-test or review policy: ${[...new Set(internalRoles)].join(', ')}.`,
+      impact: 'check may not know whether to ask for focused evidence or a review reason.',
+      fix: 'Add focused_test_recommended_for_roles or review_with_reason_allowed for this area.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+
+  for (const profileId of manualProfiles) {
+    if (BUILT_IN_MANUAL_PROFILES.has(profileId)) continue;
+    const profile = profilesById.get(profileId);
+    if (!profile) {
+      addFinding(findings, {
+        severity: 'warning',
+        code: 'MANUAL_PROFILE_NOT_FOUND',
+        areaId: area.id,
+        file: '.hive/map/validation.yaml',
+        field: field(area.id, 'verification.manual_profiles'),
+        message: `Manual profile not found: ${profileId}.`,
+        impact: 'hive validate --manual can still record evidence, but agents lack durable instructions for that profile.',
+        fix: 'Add a manual profile to validation.yaml or use a configured generic manual profile.',
+      });
+    }
+  }
+
+  const broadFallback = ((area.scope || {}).writable_broad_fallback || (area.scope || {}).writableBroadFallback || []);
+  if (broadFallback.length > 0 && verification.review_with_reason_allowed !== true) {
+    addFinding(findings, {
+      severity: 'warning',
+      code: 'BROAD_SCOPE_WITHOUT_REVIEW_POLICY',
+      areaId: area.id,
+      field: field(area.id, 'verification.review_with_reason_allowed'),
+      message: 'Area has broad fallback scope but no explicit review-with-reason policy.',
+      impact: 'Broad fallback edits should be routed through explicit human review.',
+      fix: 'Set verification.review_with_reason_allowed: true unless broad fallback edits should be blocked.',
+      relatedCommand: mapPromptCommand(area),
+    });
+  }
+}
+
+function validateRisk(area, findings) {
+  if (!area.description) {
+    addFinding(findings, {
+      severity: 'info',
+      code: 'MISSING_DESCRIPTION',
+      areaId: area.id,
+      field: field(area.id, 'description'),
+      message: 'Area description is empty.',
+      impact: 'Humans have less context when reviewing map health.',
+      fix: 'Add a one-sentence description of this work area.',
+    });
+  }
+  const tags = area.risk && area.risk.tags ? area.risk.tags : [];
+  if (tags.length === 0) {
+    addFinding(findings, {
+      severity: 'info',
+      code: 'MISSING_RISK_TAGS',
+      areaId: area.id,
+      field: field(area.id, 'risk.tags'),
+      message: 'Area risk tags are empty.',
+      impact: 'Risk review signals may be less clear.',
+      fix: 'Add simple tags such as ui, api, auth, payment, data, or ci.',
+    });
+  }
+}
+
+function readinessForArea(root, areaId, findings, area) {
+  const areaFindings = findings.filter((finding) => finding.areaId === areaId);
+  if (areaFindings.some((finding) => finding.severity === 'critical')) return 'needs_map';
+  const scope = area ? normalizeAreaScope(root, area) : null;
+  if (!scope || scope.writableDirect.length === 0) return 'discovery_only';
+  if (areaFindings.some((finding) => finding.code === 'MISSING_VALIDATION')) return 'discovery_only';
+  return 'edit_ready';
+}
+
+function summarize(result, areas, findings) {
+  const counts = {
+    critical: findings.filter((finding) => finding.severity === 'critical').length,
+    warnings: findings.filter((finding) => finding.severity === 'warning').length,
+    info: findings.filter((finding) => finding.severity === 'info').length,
+  };
+  let status = 'healthy';
+  if (result.invalidMap) status = 'invalid_map';
+  else if (counts.critical > 0) status = 'unsafe_for_edit_context';
+  else if (counts.warnings > 0) status = 'needs_attention';
+  return {
+    status,
+    summary: {
+      areasChecked: areas.length,
+      critical: counts.critical,
+      warnings: counts.warnings,
+      info: counts.info,
+    },
+  };
+}
+
+function evaluateMapHealth(root, options = {}) {
+  const initialFindings = [];
+  const areasResult = readYamlHealth(root, 'areas.yaml', { version: 1, areas: [] }, initialFindings);
+  const validationResult = readYamlHealth(root, 'validation.yaml', { version: 1, profiles: [] }, initialFindings);
+  const invalidMap = !areasResult.valid || !validationResult.valid;
+  const findings = [...initialFindings];
+  validateMapFilesNotIgnored(root, findings);
+  const areasDoc = areasResult.doc || {};
+  const validationDoc = validationResult.doc || {};
+
+  if (!Array.isArray(areasDoc.areas)) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'INVALID_SCHEMA',
+      field: 'areas',
+      message: '.hive/map/areas.yaml must contain an areas array.',
+      impact: 'Hive Lite cannot evaluate or use project areas.',
+      fix: 'Change areas.yaml to use `areas: []` or a list of area objects.',
+    });
+  }
+
+  const allAreas = Array.isArray(areasDoc.areas) ? areasDoc.areas : [];
+  const selectedAreas = options.area ? allAreas.filter((area) => area.id === options.area) : allAreas;
+  if (options.area && selectedAreas.length === 0) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'AREA_NOT_FOUND',
+      areaId: options.area,
+      field: `areas[${options.area}]`,
+      message: `Area not found: ${options.area}.`,
+      impact: 'The requested area cannot be checked.',
+      fix: 'Run hive-lite map health without --area to see configured area ids.',
+    });
+  }
+
+  const profiles = Array.isArray(validationDoc.profiles) ? validationDoc.profiles : [];
+  const profilesById = new Map(profiles.map((profile) => [profile.id, profile]));
+  const scripts = packageScripts(root);
+  const tracked = trackedFiles(root);
+  const areaIds = new Set();
+  const aliasOwners = new Map();
+  for (const area of allAreas) {
+    for (const alias of area.aliases || []) {
+      const key = String(alias).toLowerCase();
+      const owners = aliasOwners.get(key) || [];
+      owners.push(area.id || '(missing id)');
+      aliasOwners.set(key, owners);
+    }
+  }
+
+  for (const area of selectedAreas) {
+    validateAreaId(area, areaIds, findings);
+    if (!area.id) continue;
+    validateFindTerms(area, aliasOwners, findings);
+    validateEntryPoints(root, area, findings);
+    validateWritableScope(root, tracked, area, findings);
+    validateValidation(area, profilesById, scripts, findings);
+    validateVerification(area, profilesById, findings);
+    validateRisk(area, findings);
+  }
+
+  const base = { invalidMap, findings };
+  const summarized = summarize(base, selectedAreas, findings);
+  const areas = selectedAreas.map((area) => {
+    const areaFindings = findings.filter((finding) => finding.areaId === area.id);
+    const scope = normalizeAreaScope(root, area);
+    return {
+      id: area.id,
+      readiness: readinessForArea(root, area.id, findings, area),
+      critical: areaFindings.filter((finding) => finding.severity === 'critical').length,
+      warnings: areaFindings.filter((finding) => finding.severity === 'warning').length,
+      info: areaFindings.filter((finding) => finding.severity === 'info').length,
+      scope: {
+        directWritableFiles: scope.writableDirect.length,
+        broadFallbackFiles: scope.writableBroadFallback.length,
+        conditionalFiles: scope.writableConditional.length,
+        hasForbidden: scope.forbidden.length > 0,
+      },
+      evidencePolicy: {
+        roles: [...new Set(areaRoles(area))],
+        hasVerification: Boolean(area.verification),
+        directManualAllowed: Boolean(area.verification && area.verification.direct_manual_allowed === true),
+        reviewWithReasonAllowed: Boolean(area.verification && area.verification.review_with_reason_allowed === true),
+      },
+    };
+  });
+
+  const suggestions = [];
+  for (const area of selectedAreas) {
+    const areaFindings = findings.filter((finding) => finding.areaId === area.id && finding.severity !== 'info');
+    if (areaFindings.length > 0) {
+      suggestions.push({
+        kind: 'run_map_prompt',
+        areaId: area.id,
+        command: mapPromptCommand(area),
+      });
+    }
+  }
+
+  return {
+    version: 1,
+    command: 'map health',
+    generatedAt: new Date().toISOString(),
+    root,
+    status: summarized.status,
+    summary: summarized.summary,
+    options: {
+      area: options.area || null,
+    },
+    findings,
+    areas,
+    suggestions,
+    exitCode: summarized.status === 'invalid_map' ? 2 : summarized.summary.critical > 0 ? 1 : 0,
+    mapDir: path.join(hiveDir(root), 'map'),
+  };
+}
+
+module.exports = {
+  evaluateMapHealth,
+};