hive-lite 0.1.0

package/src/lib/map.js

@@ -0,0 +1,713 @@
+const fs = require('fs');
+const path = require('path');
+const { appendIfMissing, ensureDir, exists, readText, writeText } = require('./fsx');
+const { currentBranch, repoRoot, tryGit } = require('./git');
+const { roleListText } = require('./roles');
+const { parseYaml, stringifyYaml } = require('./yaml');
+
+function hiveDir(root) {
+  return path.join(root, '.hive');
+}
+
+function mapDir(root) {
+  return path.join(hiveDir(root), 'map');
+}
+
+function mapFile(root, name) {
+  return path.join(mapDir(root), name);
+}
+
+function readYamlFile(file, fallback) {
+  if (!exists(file)) return fallback;
+  return parseYaml(readText(file));
+}
+
+function writeYamlFile(file, value) {
+  writeText(file, stringifyYaml(value));
+}
+
+function ignoredDurableHiveFiles(root) {
+  const durable = [
+    '.hive/config.yaml',
+    '.hive/map/project.yaml',
+    '.hive/map/areas.yaml',
+    '.hive/map/rules.yaml',
+    '.hive/map/validation.yaml',
+  ];
+  const output = tryGit(['check-ignore', '-v', '--no-index', ...durable], { cwd: root });
+  return output ? output.split(/\r?\n/).filter(Boolean) : [];
+}
+
+function defaultProject(root) {
+  const pkgPath = path.join(root, 'package.json');
+  let packageManager = 'unknown';
+  let validation = '';
+  if (exists(path.join(root, 'pnpm-lock.yaml'))) packageManager = 'pnpm';
+  else if (exists(path.join(root, 'bun.lock')) || exists(path.join(root, 'bun.lockb'))) packageManager = 'bun';
+  else if (exists(path.join(root, 'package-lock.json'))) packageManager = 'npm';
+
+  if (exists(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readText(pkgPath));
+      const scripts = pkg.scripts || {};
+      if (scripts.typecheck) validation = `${packageManager === 'unknown' ? 'npm' : packageManager} run typecheck`;
+      else if (scripts.test) validation = `${packageManager === 'unknown' ? 'npm' : packageManager} test`;
+      else if (scripts.build) validation = `${packageManager === 'unknown' ? 'npm' : packageManager} run build`;
+    } catch {
+      validation = '';
+    }
+  }
+
+  return {
+    version: 1,
+    project: {
+      name: path.basename(root),
+      summary: 'Local Project Map + Change Control project.',
+      tech: {
+        languages: [],
+        package_manager: packageManager,
+      },
+    },
+    defaults: {
+      validation_cmd: validation,
+      baseline_branch: currentBranch(root) || 'main',
+    },
+    workspace_readiness: {
+      required: [],
+      checks: [],
+    },
+  };
+}
+
+function defaultAreas() {
+  return {
+    version: 1,
+    areas: [],
+  };
+}
+
+function defaultRules() {
+  return {
+    version: 1,
+    constraints: [
+      {
+        id: 'no_ci_weakening',
+        description: 'Do not weaken CI, validation, or deploy checks.',
+        severity: 'block',
+      },
+      {
+        id: 'code_wins_over_docs',
+        description: 'If map entries and code conflict, current code wins.',
+        severity: 'info',
+      },
+    ],
+    sensitive_paths: [
+      { pattern: '**/auth/**', reason: 'auth' },
+      { pattern: '**/permissions/**', reason: 'permissions' },
+      { pattern: '**/payment/**', reason: 'payment' },
+      { pattern: '**/billing/**', reason: 'billing' },
+      { pattern: '**/security/**', reason: 'security' },
+      { pattern: '**/secrets/**', reason: 'secrets' },
+      { pattern: '**/migrations/**', reason: 'db_migration' },
+      { pattern: '**/drizzle/**', reason: 'db_migration' },
+      { pattern: '.github/workflows/**', reason: 'ci_cd' },
+      { pattern: '**/package.json', reason: 'dependency_surface' },
+      { pattern: '**/pnpm-lock.yaml', reason: 'lockfile' },
+      { pattern: '**/bun.lock', reason: 'lockfile' },
+      { pattern: '**/package-lock.json', reason: 'lockfile' },
+    ],
+    code_owner_paths: [],
+    security_review_paths: [],
+  };
+}
+
+function defaultValidation(project) {
+  const profiles = [];
+  const command = project.defaults && project.defaults.validation_cmd;
+  if (command) {
+    profiles.push({
+      id: 'baseline',
+      description: 'Baseline project validation.',
+      command,
+      evidence_type: command.includes('test') ? 'existing_tests' : command.includes('typecheck') ? 'typecheck' : 'build',
+      covers_roles: [
+        'page',
+        'ui_component',
+        'styles',
+        'data_transform',
+        'schema_logic',
+        'cli_behavior',
+      ],
+      safety: 'safe_auto',
+    });
+  }
+  return {
+    version: 1,
+    profiles,
+  };
+}
+
+function initProject(cwd) {
+  const root = repoRoot(cwd);
+  ensureDir(hiveDir(root));
+  ensureDir(mapDir(root));
+  ensureDir(path.join(hiveDir(root), 'context'));
+  ensureDir(path.join(hiveDir(root), 'changes'));
+  ensureDir(path.join(hiveDir(root), 'deltas'));
+  ensureDir(path.join(hiveDir(root), 'patches'));
+
+  const project = defaultProject(root);
+  const files = [
+    ['config.yaml', { version: 1, mapDir: '.hive/map' }],
+    ['map/project.yaml', project],
+    ['map/areas.yaml', defaultAreas()],
+    ['map/rules.yaml', defaultRules()],
+    ['map/validation.yaml', defaultValidation(project)],
+  ];
+
+  const created = [];
+  for (const [relative, value] of files) {
+    const file = path.join(hiveDir(root), relative);
+    if (!exists(file)) {
+      writeYamlFile(file, value);
+      created.push(path.relative(root, file));
+    }
+  }
+
+  appendIfMissing(path.join(root, '.gitignore'), [
+    '.hive/state/',
+    '.hive/changes/',
+    '.hive/context/',
+    '.hive/patches/',
+  ]);
+
+  const warnings = ignoredDurableHiveFiles(root).map((line) => (
+    `durable Hive Lite map file is ignored: ${line}`
+  ));
+
+  return { root, created, warnings };
+}
+
+function loadProjectMap(root) {
+  const project = readYamlFile(mapFile(root, 'project.yaml'), defaultProject(root));
+  const areas = readYamlFile(mapFile(root, 'areas.yaml'), defaultAreas());
+  const rules = readYamlFile(mapFile(root, 'rules.yaml'), defaultRules());
+  const validation = readYamlFile(mapFile(root, 'validation.yaml'), defaultValidation(project));
+  return {
+    project,
+    areas: Array.isArray(areas.areas) ? areas.areas : [],
+    areasDoc: areas,
+    rules,
+    validation,
+    validationProfiles: Array.isArray(validation.profiles) ? validation.profiles : [],
+  };
+}
+
+function verifyProjectMap(root) {
+  const problems = [];
+  const warnings = [];
+  const required = ['project.yaml', 'areas.yaml', 'rules.yaml', 'validation.yaml'];
+  for (const name of required) {
+    const file = mapFile(root, name);
+    if (!exists(file)) problems.push(`missing .hive/map/${name}`);
+    else {
+      try {
+        parseYaml(readText(file));
+      } catch (error) {
+        problems.push(`invalid .hive/map/${name}: ${error.message}`);
+      }
+    }
+  }
+
+  if (problems.length > 0) return { problems, warnings };
+
+  const map = loadProjectMap(root);
+  const areaIds = new Set();
+  for (const area of map.areas) {
+    if (!area.id) problems.push('area missing id');
+    if (area.id && areaIds.has(area.id)) problems.push(`duplicate area id: ${area.id}`);
+    if (area.id) areaIds.add(area.id);
+    for (const entry of area.entrypoints || []) {
+      if (!entry.path) problems.push(`area ${area.id} has entrypoint without path`);
+      else if (!fs.existsSync(path.join(root, entry.path))) warnings.push(`entrypoint missing on disk: ${entry.path}`);
+    }
+  }
+
+  const profileIds = new Set();
+  for (const profile of map.validationProfiles) {
+    if (!profile.id) problems.push('validation profile missing id');
+    if (profile.id && profileIds.has(profile.id)) problems.push(`duplicate validation profile id: ${profile.id}`);
+    if (profile.id) profileIds.add(profile.id);
+    if (!profile.command && profile.type !== 'manual') warnings.push(`validation profile has no command: ${profile.id}`);
+  }
+
+  return { problems, warnings };
+}
+
+function saveAreas(root, areasDoc) {
+  writeYamlFile(mapFile(root, 'areas.yaml'), areasDoc);
+}
+
+function packageScripts(root) {
+  const pkgPath = path.join(root, 'package.json');
+  if (!exists(pkgPath)) return {};
+  try {
+    return JSON.parse(readText(pkgPath)).scripts || {};
+  } catch {
+    return {};
+  }
+}
+
+function suggestMap(root) {
+  const dirs = fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules')
+    .map((entry) => entry.name)
+    .slice(0, 20);
+  return {
+    root,
+    branch: currentBranch(root),
+    scripts: packageScripts(root),
+    topLevelDirs: dirs,
+    trackedFilesSample: tryGit(['ls-files'], { cwd: root }).split(/\r?\n/).filter(Boolean).slice(0, 60),
+  };
+}
+
+function findContextPath(root, value) {
+  const text = String(value || '').trim();
+  if (!text) return null;
+  const candidates = [];
+  if (path.isAbsolute(text)) candidates.push(text);
+  else {
+    candidates.push(path.join(root, text));
+    candidates.push(path.join(hiveDir(root), 'context', `${text}.json`));
+  }
+  if (text.endsWith('.md')) candidates.push(path.resolve(root, text).replace(/\.md$/, '.json'));
+  if (text.endsWith('.json')) candidates.push(path.resolve(root, text));
+
+  const found = candidates.find((file) => exists(file));
+  if (found && found.endsWith('.md')) return found.replace(/\.md$/, '.json');
+  return found || null;
+}
+
+function loadFindContext(root, value) {
+  const file = findContextPath(root, value);
+  if (!file || !exists(file)) {
+    throw new Error(`find context not found: ${value}; pass a ctx_xxx id or .hive/context/ctx_xxx.json`);
+  }
+  return parseYaml(readText(file));
+}
+
+function readMapText(root, name) {
+  const file = mapFile(root, name);
+  return exists(file) ? readText(file) : '';
+}
+
+function currentMapFilesSection(result) {
+  if (!result.findContext) return [];
+  const files = [
+    ['project.yaml', result.currentProjectYaml],
+    ['areas.yaml', result.currentAreasYaml],
+    ['rules.yaml', result.currentRulesYaml],
+    ['validation.yaml', result.currentValidationYaml],
+  ];
+  const lines = [];
+  for (const [name, text] of files) {
+    lines.push(`Current \`.hive/map/${name}\`:`, '```yaml', text || `# missing .hive/map/${name}`, '```', '');
+  }
+  return lines;
+}
+
+function summarizeFindContext(context) {
+  if (!context) return null;
+  const scope = context.scope || {};
+  return {
+    id: context.id,
+    intent: context.intent || {},
+    mode: context.mode || 'unknown',
+    selectedArea: context.area && context.area.id ? context.area.id : null,
+    confidence: context.confidence || {
+      level: context.area && context.area.confidence ? context.area.confidence : 'unknown',
+      reasons: context.area && context.area.matchedSignals ? context.area.matchedSignals : [],
+    },
+    warnings: context.warnings || [],
+    reviewGated: context.reviewGated || (context.explain && context.explain.reviewGated) || [],
+    candidateAreas: context.candidateAreas || [],
+    areaScores: context.explain && context.explain.areaScores ? context.explain.areaScores : [],
+    scopeQuality: scope.quality || (context.explain ? context.explain.scopeQuality : 'unknown'),
+    writableDirect: scope.writableDirect || context.writableScope || [],
+    writableConditional: scope.writableConditional || [],
+    writableBroadFallback: scope.writableBroadFallback || [],
+    forbidden: scope.forbidden || context.doNotTouch || [],
+    relevantFiles: context.relevantFiles || [],
+    validationPlan: context.validationPlan || [],
+  };
+}
+
+function clampNumber(value, fallback, min, max) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function listLines(items, render) {
+  if (!items || items.length === 0) return ['- (none)'];
+  return items.map(render);
+}
+
+function patternLine(item) {
+  if (typeof item === 'string') return `- ${item}`;
+  const reason = item.reason ? ` (${item.reason})` : '';
+  return `- ${item.pattern || item.path}${reason}`;
+}
+
+const GENERIC_AREA_IDS = new Set([
+  'dashboard',
+  'frontend',
+  'backend',
+  'server',
+  'client',
+  'components',
+  'src',
+  'app',
+  'web',
+  'ui',
+  'api',
+  'database',
+  'db',
+  'common',
+  'shared',
+  'utils',
+  'lib',
+]);
+
+function slugPart(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_');
+}
+
+function isGenericAreaId(id) {
+  const text = String(id || '').toLowerCase();
+  if (!text) return true;
+  if (!text.includes('.')) return true;
+  const last = text.split('.').pop();
+  return GENERIC_AREA_IDS.has(text) || GENERIC_AREA_IDS.has(last);
+}
+
+function suggestedAreaIdFromFind(findContext) {
+  if (!findContext) return '';
+  const selected = slugPart(findContext.selectedArea || '');
+  const parent = selected ? selected.split('_')[0] : 'area';
+  const intent = String(findContext.intent.raw || findContext.intent.summary || '').toLowerCase();
+  const text = [
+    intent,
+    ...(findContext.relevantFiles || []).map((file) => file.path || ''),
+  ].join(' ').toLowerCase();
+
+  let suffix = '';
+  if (text.includes('action') && text.includes('inbox')) suffix = 'action_inbox';
+  else if (text.includes('inbox')) suffix = 'inbox';
+  else if (text.includes('evidence')) suffix = 'evidence_viewer';
+  else if (text.includes('validation')) suffix = 'validation_flow';
+  else if (text.includes('delta')) suffix = 'delta_review';
+  else {
+    const tokens = [...new Set(text.match(/[a-z][a-z0-9]{2,}/g) || [])]
+      .filter((token) => !['should', 'with', 'that', 'this', 'from', 'into', 'feature', 'task'].includes(token))
+      .slice(0, 2);
+    suffix = tokens.map(slugPart).filter(Boolean).join('_') || 'focused_area';
+  }
+
+  return `${parent || 'area'}.${suffix}`;
+}
+
+function repairFocusFromFind(findContext, userFocus) {
+  if (!findContext) return userFocus || '';
+  const area = findContext.selectedArea || 'matched area';
+  const suggestedArea = suggestedAreaIdFromFind(findContext);
+  const warnings = (findContext.warnings || []).map((warning) => warning.code);
+  const goals = [];
+  if (isGenericAreaId(area)) goals.push(`replace generic area id with a focused id such as ${suggestedArea}`);
+  if (warnings.includes('BROAD_WRITABLE_SCOPE')) goals.push('move broad writable scope to reviewed fallback');
+  if (warnings.includes('MISSING_DIRECT_WRITABLE_SCOPE')) goals.push('add narrow writable_direct files');
+  if (warnings.includes('MISSING_ENTRYPOINT')) goals.push('add durable entrypoints');
+  if (warnings.includes('MISSING_VALIDATION')) goals.push('add validation profile references');
+  if (warnings.includes('NO_CONFIDENT_AREA')) goals.push('create or refine a focused area');
+  const suffix = goals.length ? `: ${goals.join('; ')}` : '';
+  const original = userFocus ? ` Original user intent/focus: ${userFocus}` : '';
+  return `Repair Project Map for ${area}${suffix}.${original}`;
+}
+
+function findContextPromptSection(findContext) {
+  if (!findContext) return [];
+  const suggestedArea = suggestedAreaIdFromFind(findContext);
+  const genericNote = isGenericAreaId(findContext.selectedArea)
+    ? [
+      `- selected area id is generic; do not keep it as the repaired edit area`,
+      `- suggested repaired area id: ${suggestedArea}`,
+    ]
+    : [`- suggested repaired area id: ${findContext.selectedArea || suggestedArea}`];
+  return [
+    'Find Context:',
+    `- id: ${findContext.id}`,
+    `- mode: ${findContext.mode}`,
+    `- intent: ${findContext.intent.raw || findContext.intent.summary || ''}`,
+    `- selected area: ${findContext.selectedArea || '(none)'}`,
+    `- confidence: ${findContext.confidence.level || 'unknown'}`,
+    `- scope quality: ${findContext.scopeQuality}`,
+    ...genericNote,
+    '',
+    'Find warnings:',
+    ...listLines(findContext.warnings, (warning) => `- ${warning.code}: ${warning.message}`),
+    '',
+    'Review-gated scope from find:',
+    ...listLines(findContext.reviewGated, (notice) => `- ${notice.code}: ${notice.message}`),
+    '',
+    'Candidate/area scores:',
+    ...listLines(findContext.areaScores.length ? findContext.areaScores : findContext.candidateAreas, (area) => {
+      const signals = area.signals && area.signals.length ? ` (${area.signals.slice(0, 3).join(', ')})` : '';
+      return `- ${area.id}: ${area.score == null ? 'candidate' : area.score}${signals}`;
+    }),
+    '',
+    'Relevant files from find:',
+    ...listLines(findContext.relevantFiles, (file) => `- ${file.path} [${file.source || file.role || 'unknown'}]: ${file.reason || ''}`),
+    '',
+    'Current direct writable scope:',
+    ...listLines(findContext.writableDirect, patternLine),
+    '',
+    'Current conditional writable scope:',
+    ...listLines(findContext.writableConditional, patternLine),
+    '',
+    'Current broad fallback scope:',
+    ...listLines(findContext.writableBroadFallback, patternLine),
+    '',
+    'Current forbidden scope:',
+    ...listLines(findContext.forbidden, patternLine),
+    '',
+    'Validation plan from find:',
+    ...listLines(findContext.validationPlan, (item) => `- ${item.profile || item.type || 'validation'}${item.command ? `: ${item.command}` : ''}`),
+    '',
+  ];
+}
+
+function buildMapPrompt(result) {
+  const focus = result.focus ? result.focus : '(none)';
+  const currentAreas = result.currentAreas.length
+    ? result.currentAreas.map((area) => `- ${area.id}${area.name ? `: ${area.name}` : ''}`).join('\n')
+    : '- (none yet)';
+  const scripts = Object.keys(result.repo.scripts || {}).length
+    ? JSON.stringify(result.repo.scripts, null, 2)
+    : '{}';
+  const topLevelDirs = result.repo.topLevelDirs.length
+    ? result.repo.topLevelDirs.map((dir) => `- ${dir}`).join('\n')
+    : '- (none found)';
+  const trackedFiles = result.repo.trackedFilesSample.length
+    ? result.repo.trackedFilesSample.map((file) => `- ${file}`).join('\n')
+    : '- (none found)';
+  const fromFindTask = result.findContext
+    ? [
+      'Your task: improve `.hive/map/areas.yaml` for the find gap below.',
+      'This is a Project Map repair task, not an application code task.',
+      'Do not analyze whether the business feature is already implemented.',
+      'If you are an editing-capable agent CLI, edit the relevant `.hive/map/*.yaml` files directly.',
+      'If you cannot edit files, output complete replacement YAML for every map file that needs changes.',
+    ]
+    : [
+      'Your task: draft `.hive/map/areas.yaml` with up to ' + result.maxAreas + ' high-value areas.',
+      result.maxAreas >= 3
+        ? 'Prefer 3-' + result.maxAreas + ' areas when the repo has enough distinct work areas.'
+        : 'Prefer up to ' + result.maxAreas + ' focused areas when the repo has enough distinct work areas.',
+    ];
+
+  return [
+    '# Hive Lite Map Draft Prompt',
+    '',
+    'You are helping draft a Project Map for Hive Lite.',
+    'Hive Lite is a deterministic local CLI. It does not call an LLM, run agents, or write code.',
+    '',
+    ...fromFindTask,
+    '',
+    'Boundaries:',
+    '- Group areas by user intent or work area, not by a pure directory tree.',
+    '- Do not invent nonexistent paths.',
+    '- Do not write a full architecture document.',
+    '- Do not put every file in the map.',
+    '- Only include validation or risk details that are confirmed by repo scripts or explicit files.',
+    '- If uncertain, write TODO notes instead of guessing.',
+    '- Output a draft for human review; do not claim it has been applied.',
+    '- Area ids must be dot-separated product/work ids such as `dashboard.action_inbox`; do not use one-part ids or hyphenated ids like `dashboard-inbox`.',
+    '- If the selected area id is generic or one-part, do not keep it as the repaired edit area. Replace it with a dot-separated focused area id.',
+    '- Every `writable_conditional` and `writable_broad_fallback` item must set `requires_review: true`; never output `requires_review: false` for those tiers.',
+    '- Keep broad patterns like `apps/*/src/**` only under `writable_broad_fallback`, never under `writable_direct`.',
+    '- `writable_direct` should use exact existing files unless there is a very small, justified pattern.',
+    '- Entrypoint roles must use this fixed taxonomy only: ' + roleListText() + '.',
+    '- Do not invent role names. If unsure, use `role: unknown` plus a TODO note.',
+    '- Add `source` and `confidence` to entrypoints when possible. Use `source: agent_draft` for your own draft and `confidence: low|medium|high`.',
+    '- Use only validation profile ids that exist in the current validation.yaml, or output a complete validation.yaml replacement that defines them from confirmed repo scripts.',
+    '- If a validation or manual profile is plausible but unconfirmed, put it under TODO notes or a candidate section; do not reference it as an active profile.',
+    '- Validation profiles should include `evidence_type`, `covers_roles`, and `safety` when you edit validation.yaml.',
+    '- Allowed files to edit: `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, `.hive/map/validation.yaml`.',
+    '- Do not edit application source, tests, `.gitignore`, `.hive/context`, `.hive/changes`, `.hive/deltas`, or generated artifacts.',
+    '- For `--from-find`, preserve unrelated areas exactly unless a change is required to fix the reported map gap.',
+    '- For `--from-find`, if editing files directly, output only a concise change summary and TODO notes.',
+    '- For `--from-find`, if you cannot edit files, do not output a partial patch fragment; output full replacement files.',
+    '',
+    result.findContext ? 'Map Repair Focus:' : 'Focus:',
+    focus,
+    '',
+    ...findContextPromptSection(result.findContext),
+    'Current Areas:',
+    currentAreas,
+    '',
+    'Repo Evidence:',
+    '',
+    'Package scripts:',
+    '```json',
+    scripts,
+    '```',
+    '',
+    'Top-level directories:',
+    topLevelDirs,
+    '',
+    'Tracked files sample:',
+    trackedFiles,
+    '',
+    ...currentMapFilesSection(result),
+    'Area schema example:',
+    '```yaml',
+    'version: 1',
+    'areas:',
+    '  - id: area.id',
+    '    name: Human Friendly Area Name',
+    '    description: One sentence describing the work area.',
+    '    aliases:',
+    '      - phrase users may say',
+    '    concepts:',
+    '      - concept keyword',
+    '    entrypoints:',
+    '      - path: path/to/real/file.ts',
+    '        role: ui_component',
+    '        label: Short durable label for this entrypoint',
+    '        source: agent_draft',
+    '        confidence: medium',
+    '    scope:',
+    '      readable:',
+    '        - path/to/read/**',
+    '      writable_direct:',
+    '        - path/to/real/file.ts',
+    '      writable_conditional:',
+    '        - pattern: path/to/shared/**',
+    '          reason: only if shared model changes are required',
+    '          requires_review: true',
+    '      writable_broad_fallback:',
+    '        - pattern: path/to/read/**',
+    '          reason: fallback only when direct files are insufficient',
+    '          requires_review: true',
+    '      forbidden:',
+    '        - path/to/sensitive/**',
+    '    validation:',
+    '      profiles:',
+    '        - baseline',
+    '    verification:',
+    '      direct_manual_allowed: true',
+    '      manual_profiles:',
+    '        - manual-verification',
+    '      focused_test_recommended_for_roles:',
+    '        - grouping_logic',
+    '        - data_transform',
+    '        - error_handling',
+    '      review_with_reason_allowed: true',
+    '      risk_acceptance_allowed: false',
+    '    risk:',
+    '      default_level: low',
+    '      tags:',
+    '        - ui',
+    '```',
+    '',
+    'Validation profile schema example:',
+    '```yaml',
+    'version: 1',
+    'profiles:',
+    '  - id: dashboard-build',
+    '    type: command',
+    '    command: npm run build',
+    '    evidence_type: build',
+    '    covers_roles:',
+    '      - page',
+    '      - ui_component',
+    '      - styles',
+    '    safety: safe_auto',
+    '',
+    '  - id: generic-ui-visual',
+    '    type: manual',
+    '    evidence_type: manual_visual',
+    '    instructions:',
+    '      - Open the affected UI.',
+    '      - Confirm the requested visible behavior is correct.',
+    '      - Confirm no obvious visual regression.',
+    '    covers_roles:',
+    '      - page',
+    '      - ui_component',
+    '      - styles',
+    '    safety: manual_only',
+    '```',
+    '',
+    'Return:',
+    result.findContext
+      ? '1. If you edited files directly: a concise summary of changed map files and area/profile ids.'
+      : '1. A concise `areas.yaml` draft with no more than ' + result.maxAreas + ' areas.',
+    result.findContext
+      ? '2. If you could not edit files: complete replacement YAML for every `.hive/map/*.yaml` file that needs changes.'
+      : '2. Short TODO notes for uncertain paths, validation profiles, or risk tags.',
+    result.findContext
+      ? '3. TODO notes for uncertain paths, validation profiles, or risk tags.'
+      : '3. A brief explanation of why the draft fixes the find warning or map gap.',
+    result.findContext
+      ? '4. Suggested verification commands: `hive-lite map verify`, `hive-lite map health --area <id>`, and rerun the original `hive-lite find ... --explain`.'
+      : '',
+  ].join('\n') + '\n';
+}
+
+function createMapPrompt(root, options = {}) {
+  const maxAreas = clampNumber(options.maxAreas, 8, 1, 20);
+  const findContext = options.fromFind ? summarizeFindContext(loadFindContext(root, options.fromFind)) : null;
+  const userFocus = options.focus ? String(options.focus) : '';
+  const focus = findContext ? repairFocusFromFind(findContext, userFocus) : userFocus;
+  const repo = suggestMap(root);
+  const map = loadProjectMap(root);
+  const currentAreas = map.areas.map((area) => ({
+    id: area.id || '',
+    name: area.name || '',
+    entrypoints: (area.entrypoints || []).map((entry) => entry.path).filter(Boolean),
+  }));
+  const result = {
+    root,
+    focus,
+    userFocus,
+    maxAreas,
+    fromFind: options.fromFind ? String(options.fromFind) : '',
+    findContext,
+    currentProjectYaml: findContext ? readMapText(root, 'project.yaml') : '',
+    currentAreasYaml: findContext ? readMapText(root, 'areas.yaml') : '',
+    currentRulesYaml: findContext ? readMapText(root, 'rules.yaml') : '',
+    currentValidationYaml: findContext ? readMapText(root, 'validation.yaml') : '',
+    repo,
+    currentAreas,
+  };
+  result.prompt = buildMapPrompt(result);
+  return result;
+}
+
+module.exports = {
+  createMapPrompt,
+  hiveDir,
+  initProject,
+  loadProjectMap,
+  mapDir,
+  mapFile,
+  saveAreas,
+  suggestMap,
+  verifyProjectMap,
+  writeYamlFile,
+};