hive-lite 0.1.0

package/src/lib/context.js

@@ -0,0 +1,1104 @@
+const path = require('path');
+const fs = require('fs');
+const { createId } = require('./id');
+const { ensureDir, exists, readJson, writeJson, writeText } = require('./fsx');
+const { currentBranch, currentHead, grep } = require('./git');
+const { matchesPattern } = require('./glob');
+const { hiveDir, loadProjectMap } = require('./map');
+const {
+  inferRoleFromPath,
+  isInternalBehaviorRole,
+  isUiManualRole,
+  normalizeRole,
+} = require('./roles');
+const { normalizeAreaScope, patternDisplay } = require('./scope');
+
+const DECOMPOSITION_LIMITS = {
+  relevantFilesWarning: 12,
+  relevantFilesBlocking: 20,
+  writableFilesWarning: 8,
+  writableFilesBlocking: 12,
+  highAreaScore: 6,
+  areaRatio: 1.5,
+};
+
+const AREA_NAMESPACE_TERMS = {
+  dashboard: ['dashboard', 'ui', 'frontend', 'view'],
+  server: ['server', 'api', 'backend'],
+  contracts: ['contract', 'contracts', 'schema'],
+  cli: ['cli', 'command', 'terminal'],
+};
+
+function normalize(value) {
+  return String(value || '').toLowerCase();
+}
+
+function tokenize(value) {
+  const lower = normalize(value);
+  const latin = lower.match(/[a-z0-9][a-z0-9_-]{1,}/g) || [];
+  const cjk = lower.match(/[\u4e00-\u9fff]{2,}/g) || [];
+  return [...new Set([...latin, ...cjk])];
+}
+
+function basenameTokens(file) {
+  return tokenize(path.basename(file || '').replace(/([a-z])([A-Z])/g, '$1 $2'));
+}
+
+function areaNamespace(area) {
+  return normalize(area && area.id).split(/[._:-]/).filter(Boolean)[0] || '';
+}
+
+function validationPlanForArea(map, area) {
+  const profileIds = ((area.validation || {}).profiles || []).filter(Boolean);
+  const profilesById = new Map(map.validationProfiles.map((profile) => [profile.id, profile]));
+  const selected = profileIds
+    .map((id) => profilesById.get(id))
+    .filter(Boolean)
+    .map((profile) => ({
+      profile: profile.id,
+      command: profile.command || null,
+      type: profile.type || (profile.command ? 'command' : 'manual'),
+      required: profile.required !== false && profile.type !== 'manual',
+      description: profile.description || '',
+      instructions: profile.instructions || [],
+    }));
+
+  if (selected.length === 0 && map.project.defaults && map.project.defaults.validation_cmd) {
+    selected.push({
+      profile: 'baseline',
+      command: map.project.defaults.validation_cmd,
+      type: 'command',
+      required: true,
+      description: 'Baseline project validation.',
+      instructions: [],
+    });
+  }
+  return selected;
+}
+
+function scoreArea(root, area, intent, tokens, options = {}) {
+  let score = 0;
+  const signals = [];
+  const areaText = normalize([
+    area.id,
+    area.name,
+    area.description,
+    ...(area.aliases || []),
+    ...(area.concepts || []),
+  ].join(' '));
+
+  if (options.area && area.id === options.area) {
+    score += 20;
+    signals.push(`forced area: ${area.id}`);
+  }
+
+  const namespace = areaNamespace(area);
+  const namespaceTerms = AREA_NAMESPACE_TERMS[namespace] || (namespace ? [namespace] : []);
+  const matchedNamespaceTerms = namespaceTerms.filter((term) => tokens.includes(term));
+  if (matchedNamespaceTerms.length > 0) {
+    score += 6;
+    signals.push(`area namespace: ${namespace} (${matchedNamespaceTerms.join(', ')})`);
+  }
+
+  for (const alias of area.aliases || []) {
+    const normalized = normalize(alias);
+    if (normalized && normalize(intent).includes(normalized)) {
+      score += normalized.includes(' ') ? 8 : 6;
+      signals.push(`alias: ${alias}`);
+    }
+  }
+
+  for (const concept of area.concepts || []) {
+    const normalized = normalize(concept);
+    if (normalized && normalize(intent).includes(normalized)) {
+      score += 4;
+      signals.push(`concept: ${concept}`);
+    }
+  }
+
+  for (const token of tokens) {
+    if (areaText.includes(token)) {
+      score += 2;
+      signals.push(`token: ${token}`);
+    }
+  }
+
+  for (const entry of area.entrypoints || []) {
+    const fileTokens = basenameTokens(entry.path);
+    const matched = fileTokens.filter((token) => tokens.includes(token));
+    if (matched.length > 0) {
+      score += 5 + matched.length;
+      signals.push(`entrypoint: ${entry.path}`);
+    }
+  }
+
+  return { area, score, signals };
+}
+
+function grepHints(root, tokens, maxFiles, options = {}) {
+  const fileScores = new Map();
+  for (const token of tokens.filter((item) => /^[a-z0-9_-]{3,}$/.test(item)).slice(0, 6)) {
+    for (const hit of grep(root, token, 30)) {
+      if (hit.path.startsWith('.hive/') || hit.path.includes('node_modules/')) continue;
+      if (options.allowedPatterns && options.allowedPatterns.length > 0) {
+        if (!options.allowedPatterns.some((pattern) => matchesPattern(hit.path, pattern))) continue;
+      }
+      const prev = fileScores.get(hit.path) || { path: hit.path, score: 0, hits: [] };
+      prev.score += 1;
+      if (prev.hits.length < 3) prev.hits.push({ token, line: hit.line, text: hit.text });
+      fileScores.set(hit.path, prev);
+    }
+  }
+  return [...fileScores.values()]
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+    .slice(0, maxFiles);
+}
+
+function confidenceFor(top, second) {
+  if (!top || top.score <= 0) return 'low';
+  if (top.score >= 10 && (!second || top.score > second.score * 1.5)) return 'high';
+  if (top.score >= 6) return 'medium';
+  return 'low';
+}
+
+function candidateAreasFromScored(scored) {
+  return scored
+    .filter((item) => item.score > 0)
+    .slice(0, 4)
+    .map((item) => ({
+      id: item.area.id,
+      name: item.area.name || '',
+      score: item.score,
+      signals: item.signals.slice(0, 6),
+    }));
+}
+
+function riskLevelFor(area) {
+  return area && area.risk && area.risk.default_level ? area.risk.default_level : 'low';
+}
+
+function roleForEntry(entry) {
+  return normalizeRole(entry.role) || inferRoleFromPath(entry.path);
+}
+
+function rolesForArea(area) {
+  return [...new Set((area.entrypoints || []).map(roleForEntry).filter(Boolean))];
+}
+
+function evidenceClassesForRoles(roles) {
+  const classes = new Set();
+  for (const role of roles) {
+    if (isUiManualRole(role)) classes.add('direct_manual_verifiable');
+    else if (role === 'api_contract' || role === 'schema_logic') classes.add('schema_or_contract');
+    else if (isInternalBehaviorRole(role)) classes.add('internal_logic');
+    else if (role === 'config') classes.add('config_review');
+    else if (role === 'test') classes.add('test_change');
+    else classes.add('unknown_policy');
+  }
+  return [...classes];
+}
+
+function validationSurfaceForProfile(profile) {
+  if (normalize(profile.type) === 'manual') return null;
+  const id = String(profile.profile || profile.id || '').toLowerCase();
+  if (!id) return 'unknown';
+  const first = id.split(/[._:-]/).filter(Boolean)[0];
+  return first || id;
+}
+
+function validationSurfacesForArea(map, area) {
+  const profilesById = new Map(map.validationProfiles.map((profile) => [profile.id, profile]));
+  return ((area.validation || {}).profiles || [])
+    .map((id) => profilesById.get(id) || { id })
+    .map(validationSurfaceForProfile)
+    .filter(Boolean);
+}
+
+function splitDir(root) {
+  return path.join(hiveDir(root), 'context', 'splits');
+}
+
+function splitJsonPath(root, splitId) {
+  return path.join(splitDir(root), `${splitId}.json`);
+}
+
+function splitMarkdownPath(root, splitId) {
+  return path.join(splitDir(root), `${splitId}.md`);
+}
+
+function phaseIdForArea(areaId) {
+  return `phase_${String(areaId || 'unknown').replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase()}`;
+}
+
+function relativePath(root, file) {
+  return path.relative(root, file).replace(/\\/g, '/');
+}
+
+function shellQuote(value) {
+  const text = String(value || '');
+  if (/^[A-Za-z0-9_/:.,@%+=-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, "'\\''")}'`;
+}
+
+function commandLine(parts) {
+  return parts.map(shellQuote).join(' ');
+}
+
+function normalizeCommandArgv(value) {
+  if (Array.isArray(value)) {
+    const parts = value.map((item) => String(item || '')).filter(Boolean);
+    if (parts.length > 0) return parts;
+  }
+  return ['hive-lite'];
+}
+
+function sameArgv(left, right) {
+  if (left.length !== right.length) return false;
+  return left.every((item, index) => item === right[index]);
+}
+
+function findCommandForPhase(argv, note, phase) {
+  return commandLine([
+    ...argv,
+    'find',
+    phase.findIntent,
+    '--from-split',
+    note.id,
+    '--phase',
+    phase.id,
+    '--area',
+    phase.primaryAreaId,
+  ]);
+}
+
+function intentHasMultiStepMarkers(intent) {
+  const text = normalize(intent);
+  return [
+    /同时|顺便|还要|以及|并且|一起|全局|整体|全栈|端到端|前后端|架构|迁移|改版|重构/,
+    /\b(both|across|between)\b[\s\S]{0,60}\b(places|surfaces|areas|components|commands|outputs)\b/,
+    /\b(share|same|shared)\b[\s\S]{0,60}\b(wording|copy|label|labels|output|display)\b/,
+    /\b(ui|frontend|dashboard)\b[\s\S]{0,40}\b(api|server|backend|schema|contract|database|db)\b/,
+    /\b(api|server|backend|schema|contract|database|db)\b[\s\S]{0,40}\b(ui|frontend|dashboard)\b/,
+  ].some((pattern) => pattern.test(text));
+}
+
+function signal(code, message, data = {}) {
+  return {
+    code,
+    message,
+    severity: data.severity || 'blocking',
+    blocking: data.blocking !== false,
+    ...data,
+  };
+}
+
+function highScoringAreas(scored) {
+  const topScore = scored[0] ? scored[0].score : 0;
+  return scored
+    .filter((item) => item.score >= DECOMPOSITION_LIMITS.highAreaScore)
+    .filter((item) => topScore === 0 || item.score >= topScore / 2)
+    .slice(0, 5);
+}
+
+function competingHighScoringAreas(scored) {
+  const highAreas = highScoringAreas(scored);
+  const topScore = highAreas[0] ? highAreas[0].score : 0;
+  if (highAreas.length < 2 || topScore <= 0) return highAreas;
+  return highAreas.filter((item, index) => (
+    index === 0 || topScore <= item.score * DECOMPOSITION_LIMITS.areaRatio
+  ));
+}
+
+function decompositionSignals({ map, area, confidence, intent, relevant, scope, scored, validationPlan, constrainedAreaId }) {
+  if (!area) return [];
+  const signals = [];
+  const highAreas = highScoringAreas(scored)
+    .filter((item) => !constrainedAreaId || item.area.id === constrainedAreaId);
+  const competingAreas = competingHighScoringAreas(scored)
+    .filter((item) => !constrainedAreaId || item.area.id === constrainedAreaId);
+
+  if (competingAreas.length >= 2) {
+    signals.push(signal('MULTIPLE_HIGH_SCORING_AREAS', 'Multiple areas scored high enough that this intent may not fit one Context Packet.', {
+      areas: competingAreas.map((item) => ({ id: item.area.id, score: item.score })),
+    }));
+  }
+
+  if (confidence === 'medium' && competingAreas.length >= 2) {
+    signals.push(signal('FIND_CONFIDENCE_AMBIGUOUS', 'Top area is not clearly separated from other candidate areas.', {
+      areas: competingAreas.map((item) => ({ id: item.area.id, score: item.score })),
+    }));
+  }
+
+  if (relevant.length > DECOMPOSITION_LIMITS.relevantFilesBlocking) {
+    signals.push(signal('TOO_MANY_RELEVANT_FILES', 'Relevant files exceed the safe edit-context limit.', {
+      count: relevant.length,
+      threshold: DECOMPOSITION_LIMITS.relevantFilesBlocking,
+    }));
+  } else if (relevant.length > DECOMPOSITION_LIMITS.relevantFilesWarning) {
+    signals.push(signal('TOO_MANY_RELEVANT_FILES', 'Relevant files are high for a single Context Packet.', {
+      severity: 'warning',
+      blocking: false,
+      count: relevant.length,
+      threshold: DECOMPOSITION_LIMITS.relevantFilesWarning,
+    }));
+  }
+
+  if (scope.writableDirect.length > DECOMPOSITION_LIMITS.writableFilesBlocking) {
+    signals.push(signal('TOO_MANY_WRITABLE_FILES', 'Direct writable files exceed the safe change boundary.', {
+      count: scope.writableDirect.length,
+      threshold: DECOMPOSITION_LIMITS.writableFilesBlocking,
+    }));
+  } else if (scope.writableDirect.length > DECOMPOSITION_LIMITS.writableFilesWarning) {
+    signals.push(signal('TOO_MANY_WRITABLE_FILES', 'Direct writable files are high for one Change Record.', {
+      severity: 'warning',
+      blocking: false,
+      count: scope.writableDirect.length,
+      threshold: DECOMPOSITION_LIMITS.writableFilesWarning,
+    }));
+  }
+
+  const areasForPolicy = competingAreas.length >= 2 ? competingAreas.map((item) => item.area) : [area];
+  const evidenceClasses = new Set();
+  for (const itemArea of areasForPolicy) {
+    for (const item of evidenceClassesForRoles(rolesForArea(itemArea))) evidenceClasses.add(item);
+  }
+  if (competingAreas.length >= 2 && evidenceClasses.size > 1) {
+    signals.push(signal('MULTIPLE_EVIDENCE_CLASSES', 'Candidate areas imply different evidence policies.', {
+      classes: [...evidenceClasses],
+    }));
+  }
+
+  const validationSurfaces = new Set(validationPlan.map(validationSurfaceForProfile).filter(Boolean));
+  if (competingAreas.length >= 2) {
+    for (const item of competingAreas.slice(1)) {
+      for (const surface of validationSurfacesForArea(map, item.area)) validationSurfaces.add(surface);
+    }
+  }
+  if (validationSurfaces.size > 1) {
+    signals.push(signal('MULTIPLE_VALIDATION_SURFACES', 'The intent appears to involve more than one validation surface.', {
+      surfaces: [...validationSurfaces],
+    }));
+  }
+
+  const riskLevels = new Set(areasForPolicy.map(riskLevelFor));
+  if (riskLevels.size > 1) {
+    signals.push(signal('MIXED_RISK_LEVELS', 'Candidate areas have mixed risk levels.', {
+      levels: [...riskLevels],
+    }));
+  }
+
+  if (intentHasMultiStepMarkers(intent) && highAreas.length >= 2) {
+    signals.push(signal('INTENT_HAS_MULTI_STEP_MARKERS', 'Intent wording suggests multiple phases or surfaces.', {
+      areas: highAreas.map((item) => ({ id: item.area.id, score: item.score })),
+    }));
+  }
+
+  return signals;
+}
+
+function candidatePhaseSeeds(scored, intent) {
+  return highScoringAreas(scored).map((item, index) => {
+    const area = item.area;
+    const roles = rolesForArea(area);
+    return {
+      id: phaseIdForArea(area.id),
+      order: (index + 1) * 10,
+      areaId: area.id,
+      areaName: area.name || '',
+      score: item.score,
+      phaseHint: area.name || area.id,
+      findIntent: `${intent} [focus: ${area.id}]`,
+      roles,
+      evidenceClasses: evidenceClassesForRoles(roles),
+      validationProfiles: ((area.validation || {}).profiles || []).filter(Boolean),
+      risk: riskLevelFor(area),
+      reason: item.signals.slice(0, 4).join(', '),
+    };
+  });
+}
+
+function preconditionsForPhase(phase, allPhases) {
+  const sorted = allPhases.slice().sort((a, b) => (a.order || 0) - (b.order || 0));
+  const previous = sorted.filter((item) => (item.order || 0) < (phase.order || 0));
+  return {
+    requiredAcceptedPhases: previous.slice(-1).map((item) => item.id),
+    recommendedAfterPhases: previous.slice(0, -1).map((item) => item.id),
+    reason: previous.length
+      ? 'Earlier phases are recommended because they may define assumptions for this phase.'
+      : 'This is the first recommended phase for the split note.',
+  };
+}
+
+function buildSplitMarkdown(note) {
+  const currentArgv = normalizeCommandArgv(note.cliCommand && note.cliCommand.argv);
+  const packageAliasArgv = ['hive-lite'];
+  const lines = [
+    `# Hive Lite Split Note: ${note.id}`,
+    '',
+    'This note is a context artifact, not a task list or workflow state machine.',
+    '',
+    '## Original Intent',
+    note.source.originalIntent,
+    '',
+    '## Why This Was Split',
+    note.reason.summary,
+    '',
+    ...note.reason.signals.map((item) => `- ${item}`),
+    '',
+    '## Phases',
+  ];
+
+  for (const phase of note.phases) {
+    lines.push(
+      '',
+      `### ${phase.title}`,
+      '',
+      `Area: ${phase.primaryAreaId}`,
+      '',
+      'Run with this Hive Lite CLI invocation:',
+      '',
+      '```bash',
+      findCommandForPhase(currentArgv, note, phase),
+      '```',
+      '',
+      ...(!sameArgv(currentArgv, packageAliasArgv) ? [
+        'If the package alias is installed:',
+        '',
+        '```bash',
+        findCommandForPhase(packageAliasArgv, note, phase),
+        '```',
+        '',
+      ] : []),
+      'Expected Evidence:',
+      ...(phase.expectedEvidence.length ? phase.expectedEvidence.map((item) => `- ${item}`) : ['- (not configured)']),
+      '',
+      'Non-goals:',
+      ...(phase.nonGoals.length ? phase.nonGoals.map((item) => `- ${item}`) : ['- Do not combine this phase with other areas.']),
+    );
+  }
+
+  lines.push(
+    '',
+    '## Rule',
+    '',
+    'Each phase must independently run:',
+    '',
+    '```text',
+    'find -> check -> validate -> accept',
+    '```',
+    '',
+    'Do not combine phases into one coding prompt.',
+  );
+
+  return `${lines.join('\n')}\n`;
+}
+
+function createSplitNote(root, packet, phaseSeeds, decomposition, options = {}) {
+  const splitId = createId('split');
+  ensureDir(splitDir(root));
+  const jsonPath = splitJsonPath(root, splitId);
+  const markdownPath = splitMarkdownPath(root, splitId);
+  const cliCommandArgv = normalizeCommandArgv(options.cliCommandArgv);
+  const note = {
+    schemaVersion: 'hive-lite/split-note/v1',
+    id: splitId,
+    createdAt: new Date().toISOString(),
+    cliCommand: {
+      kind: sameArgv(cliCommandArgv, ['hive-lite']) ? 'package_alias' : 'current_invocation',
+      argv: cliCommandArgv,
+      rendered: commandLine(cliCommandArgv),
+    },
+    source: {
+      kind: 'find',
+      contextPacketId: packet.id,
+      originalIntent: packet.intent.raw,
+    },
+    reason: {
+      mode: 'needs_decomposition',
+      signals: decomposition.map((item) => item.code),
+      summary: 'This intent cannot safely become one Context Packet and one Change Record.',
+    },
+    phases: phaseSeeds.map((phase) => ({
+      id: phase.id,
+      order: phase.order,
+      title: phase.phaseHint,
+      findIntent: phase.findIntent,
+      primaryAreaId: phase.areaId,
+      expectedEvidence: [
+        ...(phase.validationProfiles || []).map((profile) => `validation:${profile}`),
+        ...(phase.evidenceClasses || []).map((item) => `evidence:${item}`),
+      ],
+      nonGoals: phaseSeeds
+        .filter((other) => other.areaId !== phase.areaId)
+        .map((other) => `Do not change ${other.areaId} in this phase.`),
+      preconditions: preconditionsForPhase(phase, phaseSeeds),
+      linkedContextIds: [],
+      linkedChangeIds: [],
+    })),
+    notes: [
+      'Each phase must rerun hive find.',
+      'Do not combine phases into one coding prompt.',
+      'Each phase should produce its own Change Record and acceptance evidence.',
+    ],
+  };
+  writeJson(jsonPath, note);
+  writeText(markdownPath, buildSplitMarkdown(note));
+  return {
+    id: splitId,
+    jsonPath: relativePath(root, jsonPath),
+    markdownPath: relativePath(root, markdownPath),
+  };
+}
+
+function acceptedPhasesForSplit(root, splitId) {
+  const dir = path.join(hiveDir(root), 'changes');
+  if (!exists(dir)) return new Map();
+  const accepted = new Map();
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith('chg_')) continue;
+    const file = path.join(dir, entry.name, 'change.json');
+    if (!exists(file)) continue;
+    try {
+      const change = readJson(file);
+      const origin = change.originSplit || {};
+      if (origin.splitId !== splitId || !origin.phaseId) continue;
+      if (!change.humanDecision || change.humanDecision.status !== 'accepted') continue;
+      const current = accepted.get(origin.phaseId) || [];
+      current.push({
+        changeId: change.id,
+        commit: change.humanDecision.commit || null,
+        acceptedAt: change.humanDecision.decidedAt || null,
+      });
+      accepted.set(origin.phaseId, current);
+    } catch {
+      // Ignore malformed historical change records.
+    }
+  }
+  return accepted;
+}
+
+function loadSplitNote(root, splitId) {
+  if (!splitId) return null;
+  const file = splitJsonPath(root, splitId);
+  if (!exists(file)) return null;
+  return readJson(file);
+}
+
+function phaseDependencyStatus(root, originSplit) {
+  if (!originSplit || !originSplit.splitId || !originSplit.phaseId) return null;
+  const note = loadSplitNote(root, originSplit.splitId);
+  if (!note || !Array.isArray(note.phases)) {
+    return {
+      canStartNormally: false,
+      splitFound: false,
+      phaseFound: false,
+      requiredAcceptedPhases: [],
+      recommendedAfterPhases: [],
+      missingRequiredAcceptedPhases: [],
+      readyRequiredAcceptedPhases: [],
+      missingRecommendedAfterPhases: [],
+      readyRecommendedAfterPhases: [],
+      message: 'Split note was not found; dependency status cannot be derived.',
+    };
+  }
+  const phase = note.phases.find((item) => item.id === originSplit.phaseId);
+  if (!phase) {
+    return {
+      canStartNormally: false,
+      splitFound: true,
+      phaseFound: false,
+      requiredAcceptedPhases: [],
+      recommendedAfterPhases: [],
+      missingRequiredAcceptedPhases: [],
+      readyRequiredAcceptedPhases: [],
+      missingRecommendedAfterPhases: [],
+      readyRecommendedAfterPhases: [],
+      message: 'Phase was not found in the split note; dependency status cannot be derived.',
+    };
+  }
+  const accepted = acceptedPhasesForSplit(root, originSplit.splitId);
+  const preconditions = phase.preconditions || {};
+  const required = preconditions.requiredAcceptedPhases || [];
+  const recommended = preconditions.recommendedAfterPhases || [];
+  const readyRequired = required.filter((phaseId) => accepted.has(phaseId));
+  const missingRequired = required.filter((phaseId) => !accepted.has(phaseId));
+  const readyRecommended = recommended.filter((phaseId) => accepted.has(phaseId));
+  const missingRecommended = recommended.filter((phaseId) => !accepted.has(phaseId));
+  return {
+    canStartNormally: missingRequired.length === 0,
+    splitFound: true,
+    phaseFound: true,
+    requiredAcceptedPhases: required.map((phaseId) => ({
+      phaseId,
+      status: accepted.has(phaseId) ? 'accepted' : 'missing',
+      acceptedChangeIds: (accepted.get(phaseId) || []).map((item) => item.changeId),
+    })),
+    recommendedAfterPhases: recommended.map((phaseId) => ({
+      phaseId,
+      status: accepted.has(phaseId) ? 'accepted' : 'missing',
+      acceptedChangeIds: (accepted.get(phaseId) || []).map((item) => item.changeId),
+    })),
+    missingRequiredAcceptedPhases: missingRequired,
+    readyRequiredAcceptedPhases: readyRequired,
+    missingRecommendedAfterPhases: missingRecommended,
+    readyRecommendedAfterPhases: readyRecommended,
+    message: missingRequired.length
+      ? `This phase has unmet required phase dependencies: ${missingRequired.join(', ')}.`
+      : 'Required phase dependencies are satisfied.',
+  };
+}
+
+function originSplitFromOptions(options = {}) {
+  const splitId = options.fromSplit || options.fromsplit || null;
+  const phaseId = options.phase || null;
+  if (!splitId && !phaseId) return null;
+  return {
+    splitId: splitId && splitId !== true ? String(splitId) : null,
+    phaseId: phaseId && phaseId !== true ? String(phaseId) : null,
+  };
+}
+
+function phaseFromOriginSplit(root, originSplit) {
+  if (!originSplit || !originSplit.splitId || !originSplit.phaseId) return null;
+  const note = loadSplitNote(root, originSplit.splitId);
+  if (!note || !Array.isArray(note.phases)) return null;
+  return note.phases.find((item) => item.id === originSplit.phaseId) || null;
+}
+
+function validAreaId(map, areaId) {
+  if (!areaId || areaId === true) return null;
+  const normalized = String(areaId);
+  return map.areas.some((area) => area.id === normalized) ? normalized : null;
+}
+
+function requestedAreaId(options = {}) {
+  if (!options.area || options.area === true) return null;
+  return String(options.area);
+}
+
+function missingSplitReference(phaseStatus) {
+  return Boolean(phaseStatus && (phaseStatus.splitFound === false || phaseStatus.phaseFound === false));
+}
+
+function splitRoutingWarnings(originSplit, phaseStatus, originPhaseAreaId, requestedArea) {
+  const warnings = [];
+  if (phaseStatus && phaseStatus.splitFound === false) {
+    warnings.push({
+      code: 'SPLIT_NOTE_NOT_FOUND',
+      message: `Split note ${originSplit.splitId} was not found; this copied split command is not an edit permit.`,
+    });
+  } else if (phaseStatus && phaseStatus.phaseFound === false) {
+    warnings.push({
+      code: 'SPLIT_PHASE_NOT_FOUND',
+      message: `Phase ${originSplit.phaseId} was not found in split ${originSplit.splitId}; this copied split command is not an edit permit.`,
+    });
+  }
+  if (originPhaseAreaId && requestedArea && requestedArea !== originPhaseAreaId) {
+    warnings.push({
+      code: 'SPLIT_PHASE_AREA_OVERRIDE',
+      message: `Ignoring --area ${requestedArea}; split phase ${originSplit.phaseId} requires ${originPhaseAreaId}.`,
+    });
+  }
+  return warnings;
+}
+
+function scopeWarnings(scope) {
+  const warnings = [];
+  if (scope.writableDirect.length === 0) {
+    warnings.push({
+      code: 'MISSING_DIRECT_WRITABLE_SCOPE',
+      message: 'No narrow writable_direct scope is available.',
+    });
+  }
+  return warnings;
+}
+
+function reviewGatedNotices(scope) {
+  const notices = [];
+  for (const item of scope.writableConditional) {
+    notices.push({
+      code: 'CONDITIONAL_WRITABLE_SCOPE',
+      tier: 'conditional',
+      pattern: item.pattern,
+      message: `Conditional writable scope requires review: ${patternDisplay(item)}`,
+    });
+  }
+  for (const item of scope.writableBroadFallback) {
+    notices.push({
+      code: 'BROAD_WRITABLE_SCOPE',
+      tier: 'broad_fallback',
+      pattern: item.pattern,
+      message: `Broad writable fallback requires review: ${patternDisplay(item)}`,
+    });
+  }
+  return notices;
+}
+
+function contextMode(area, scope, validationPlan, relevant, decomposition = []) {
+  if (!area) return 'needs_map';
+  if (decomposition.some((item) => item.blocking)) return 'needs_decomposition';
+  if (scope.writableDirect.length === 0) return 'discovery_context';
+  if (relevant.length === 0 || !relevant.some((file) => file.source === 'project_map')) return 'discovery_context';
+  if (validationPlan.length === 0) return 'discovery_context';
+  return 'edit_context';
+}
+
+function recommendedActions(mode, intent, contextId, phaseStatus) {
+  const focus = JSON.stringify(intent);
+  if (missingSplitReference(phaseStatus)) {
+    return [
+      'Do not give this Context Packet to a coding agent.',
+      'Find the current split note with hive-lite status --json, or rerun the original broad find command to create a fresh split note.',
+    ];
+  }
+  if (mode === 'edit_context') return [];
+  if (mode === 'needs_decomposition') {
+    return [
+      'Do not generate a coding prompt from this Context Packet.',
+      'Ask the human to choose one smaller phase, then run hive-lite find again for that phase.',
+    ];
+  }
+  return [
+    `hive-lite map prompt --focus ${focus} --from-find ${contextId}`,
+    'Review and narrow .hive/map/areas.yaml, then run hive-lite find again.',
+  ];
+}
+
+function agentInstructionsFor(mode) {
+  if (mode === 'edit_context') {
+    return [
+      'Only modify Writable Scope unless you explicitly report stuck.',
+      'Do not change files listed under Do Not Touch.',
+      'Conditional or broad fallback files require human review.',
+      'If the fix requires broader scope, stop and ask for a refined context packet.',
+      'After editing, stop and let the human run hive check.',
+    ];
+  }
+  if (mode === 'discovery_context') {
+    return [
+      'Use this packet for investigation only; the map is not precise enough for safe editing.',
+      'Do not edit until the Project Map has a narrower writable_direct scope.',
+      'Report which files should become entrypoints or writable_direct candidates.',
+    ];
+  }
+  if (mode === 'needs_decomposition') {
+    return [
+      'Do not edit code from this packet.',
+      'Do not merge candidate areas into one broad prompt.',
+      'Split the intent into smaller phases and rerun hive find for the selected phase.',
+    ];
+  }
+  return [
+    'Do not edit code from this packet.',
+    'Improve the Project Map first, then rerun hive find.',
+  ];
+}
+
+function buildContextMarkdown(packet) {
+  const lines = [
+    `# Hive Context Packet ${packet.id}`,
+    '',
+    '## Mode',
+    packet.mode,
+    '',
+    '## Intent',
+    packet.intent.summary,
+    '',
+    '## Likely Area',
+    packet.area ? `- ${packet.area.id} (${packet.area.confidence})` : '- unknown',
+    '',
+    ...(!packet.area ? [
+      '## Candidate Areas',
+      ...(packet.candidateAreas.length
+        ? packet.candidateAreas.map((item) => `- ${item.id} (score ${item.score}): ${item.signals.join(', ') || 'matched weakly'}`)
+        : ['- (none matched)']),
+      '',
+      '## Map Guidance',
+      '- Add aliases/concepts that match the intent wording.',
+      '- Add entrypoints for files an agent should inspect first.',
+      `- Consider: hive-lite map prompt --focus ${JSON.stringify(packet.intent.raw)} --from-find ${packet.id}`,
+      '',
+    ] : []),
+    ...(packet.warnings.length ? [
+      '## Warnings',
+      ...packet.warnings.map((item) => `- ${item.code}: ${item.message}`),
+      '',
+    ] : []),
+    ...(packet.reviewGated.length ? [
+      '## Review-Gated Scope',
+      ...packet.reviewGated.map((item) => `- ${item.code}: ${item.message}`),
+      '',
+    ] : []),
+    ...(packet.decompositionSignals && packet.decompositionSignals.length ? [
+      '## Decomposition Required',
+      ...packet.decompositionSignals.map((item) => `- ${item.code}: ${item.message}`),
+      '',
+      ...(packet.splitNote ? [
+        '## Split Note',
+        `- ${packet.splitNote.markdownPath}`,
+        '',
+      ] : []),
+      '## Candidate Phase Seeds',
+      ...(packet.candidatePhaseSeeds.length
+        ? packet.candidatePhaseSeeds.map((item) => `- ${item.id} (${item.areaId}): rerun find with ${JSON.stringify(item.findIntent)}`)
+        : ['- (none)']),
+      '',
+    ] : []),
+    ...(packet.phaseDependencyStatus && packet.phaseDependencyStatus.canStartNormally === false ? [
+      '## Phase Dependency Status',
+      `- ${packet.phaseDependencyStatus.message}`,
+      ...packet.phaseDependencyStatus.missingRequiredAcceptedPhases.map((item) => `- Missing required phase: ${item}`),
+      '',
+    ] : []),
+    '## Relevant Files',
+    ...packet.relevantFiles.map((file) => `- ${file.path} (${file.role || file.source}): ${file.reason}`),
+    '',
+    '## Writable Scope',
+    ...(packet.writableScope.length ? packet.writableScope.map((item) => `- ${item}`) : ['- (none; this is not an edit permit)']),
+    '',
+    '## Conditional Writable Scope',
+    ...(packet.scope.writableConditional.length ? packet.scope.writableConditional.map((item) => `- ${patternDisplay(item)}`) : ['- (none configured)']),
+    '',
+    '## Broad Fallback Scope',
+    ...(packet.scope.writableBroadFallback.length ? packet.scope.writableBroadFallback.map((item) => `- ${patternDisplay(item)}`) : ['- (none configured)']),
+    '',
+    '## Readable Scope',
+    ...(packet.readableScope.length ? packet.readableScope.map((item) => `- ${item}`) : ['- (local code search inside relevant files only)']),
+    '',
+    '## Do Not Touch',
+    ...(packet.doNotTouch.length ? packet.doNotTouch.map((item) => `- ${item}`) : ['- (none configured)']),
+    '',
+    '## Validation',
+    ...(packet.validationPlan.length ? packet.validationPlan.map((item) => {
+      if (item.command) return `- ${item.required ? 'Required' : 'Optional'}: ${item.command}`;
+      return `- ${item.required ? 'Required' : 'Optional'} manual: ${item.description || item.profile}`;
+    }) : ['- (none configured; do not invent a technology-specific command)']),
+    '',
+    '## Risk',
+    `- ${packet.risk.level}: ${packet.risk.reasons.join('; ') || 'no configured risk signal'}`,
+    '',
+    '## Agent Instructions',
+    ...packet.agentInstructions.map((item) => `- ${item}`),
+  ];
+
+  if (packet.questions.length > 0) {
+    lines.push('', '## Questions', ...packet.questions.map((item) => `- ${item}`));
+  }
+
+  if (packet.recommendedActions.length > 0) {
+    lines.push('', '## Recommended Actions', ...packet.recommendedActions.map((item) => `- ${item}`));
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function createContextPacket(root, intent, options = {}) {
+  const map = loadProjectMap(root);
+  const originSplit = originSplitFromOptions(options);
+  const originPhase = phaseFromOriginSplit(root, originSplit);
+  const phaseStatus = phaseDependencyStatus(root, originSplit);
+  const originPhaseAreaId = validAreaId(map, originPhase && originPhase.primaryAreaId);
+  const requestedArea = requestedAreaId(options);
+  const constrainedAreaId = originPhaseAreaId || validAreaId(map, requestedArea);
+  const findOptions = { ...options };
+  if (originPhaseAreaId) {
+    findOptions.area = originPhaseAreaId;
+  } else if (constrainedAreaId) {
+    findOptions.area = constrainedAreaId;
+  }
+  const tokens = tokenize(intent);
+  const maxFiles = Number(options.maxFiles || 8);
+  const allScored = map.areas
+    .map((area) => scoreArea(root, area, intent, tokens, findOptions))
+    .sort((a, b) => b.score - a.score);
+  const scored = constrainedAreaId
+    ? allScored.filter((item) => item.area.id === constrainedAreaId)
+    : allScored;
+  const top = scored[0] || null;
+  const second = scored[1] || null;
+  const confidence = confidenceFor(top, second);
+  const area = confidence === 'low' && !constrainedAreaId ? null : top && top.score > 0 ? top.area : null;
+  const candidateAreas = candidateAreasFromScored(scored);
+  const scope = area ? normalizeAreaScope(root, area) : {
+    readable: [],
+    writableDirect: [],
+    writableConditional: [],
+    writableBroadFallback: [],
+    forbidden: [],
+    quality: 'unknown',
+  };
+  const restrictGrepToReadable = area && (confidence === 'high' || findOptions.area) && scope.readable.length > 0;
+  const grepFiles = grepHints(root, tokens, maxFiles, {
+    allowedPatterns: restrictGrepToReadable ? scope.readable : [],
+  });
+
+  const relevant = [];
+  const seen = new Set();
+  if (area) {
+    for (const entry of area.entrypoints || []) {
+      if (!entry.path || seen.has(entry.path)) continue;
+      seen.add(entry.path);
+      relevant.push({
+        path: entry.path,
+        role: entry.role || 'entrypoint',
+        reason: entry.reason || `project map entrypoint for ${area.id}`,
+        source: 'project_map',
+        confidence,
+      });
+    }
+  }
+  for (const hit of grepFiles) {
+    if (seen.has(hit.path) || relevant.length >= maxFiles) continue;
+    seen.add(hit.path);
+    relevant.push({
+      path: hit.path,
+      role: 'grep_hit',
+      reason: `matched intent terms: ${hit.hits.map((item) => item.token).join(', ')}`,
+      source: 'git_grep',
+      confidence: 'medium',
+    });
+  }
+
+  const id = createId('ctx');
+  const validationPlan = area ? validationPlanForArea(map, area) : [];
+  const warnings = [];
+  if (!area) {
+    warnings.push({
+      code: 'NO_CONFIDENT_AREA',
+      message: 'No project map area matched this intent with enough confidence.',
+    });
+  } else {
+    warnings.push(...scopeWarnings(scope));
+    if (relevant.length === 0 || !relevant.some((file) => file.source === 'project_map')) {
+      warnings.push({
+        code: 'MISSING_ENTRYPOINT',
+        message: 'No project map entrypoint was available for this context.',
+      });
+    }
+    if (validationPlan.length === 0) {
+      warnings.push({
+        code: 'MISSING_VALIDATION',
+        message: 'No validation profile or default validation command is configured.',
+      });
+    }
+  }
+  const reviewGated = area ? reviewGatedNotices(scope) : [];
+  warnings.push(...splitRoutingWarnings(originSplit, phaseStatus, originPhaseAreaId, requestedArea));
+  const decomposition = decompositionSignals({
+    map,
+    area,
+    confidence,
+    intent,
+    relevant,
+    scope,
+    scored,
+    validationPlan,
+    constrainedAreaId,
+  });
+  const phaseSeeds = decomposition.length > 0 ? candidatePhaseSeeds(scored, intent) : [];
+  let mode = contextMode(area, scope, validationPlan, relevant, decomposition);
+  if (missingSplitReference(phaseStatus) && mode === 'edit_context') mode = 'discovery_context';
+  const actions = recommendedActions(mode, intent, id, phaseStatus);
+  const packet = {
+    version: 1,
+    id,
+    createdAt: new Date().toISOString(),
+    repo: {
+      root,
+      head: currentHead(root),
+      branch: currentBranch(root),
+    },
+    intent: {
+      raw: intent,
+      kind: options.kind || 'unknown',
+      summary: intent,
+    },
+    area: area ? {
+      id: area.id,
+      confidence,
+      matchedSignals: top.signals,
+      alternatives: scored.slice(1, 4).filter((item) => item.score > 0).map((item) => ({
+        id: item.area.id,
+        score: item.score,
+        signals: item.signals.slice(0, 4),
+      })),
+    } : null,
+    mode,
+    confidence: {
+      level: area ? confidence : 'low',
+      topScore: top ? top.score : 0,
+      reasons: area ? top.signals.slice(0, 8) : ['no unique area'],
+    },
+    candidateAreas,
+    originSplit,
+    phaseDependencyStatus: phaseStatus,
+    relevantFiles: relevant,
+    scope,
+    writableScope: scope.writableDirect.slice(),
+    readableScope: scope.readable.slice(),
+    doNotTouch: scope.forbidden.slice(),
+    validationPlan,
+    warnings,
+    reviewGated,
+    decompositionSignals: decomposition,
+    candidatePhaseSeeds: phaseSeeds,
+    recommendedActions: actions,
+    contextBoundary: area ? {
+      maxPrimaryAreas: 1,
+      primaryAreaId: area.id,
+      stopIfRequiresConditionalScope: true,
+      stopIfNeedsAreas: phaseSeeds
+        .map((item) => item.areaId)
+        .filter((areaId) => areaId !== area.id),
+    } : null,
+    risk: {
+      level: area && area.risk && area.risk.default_level ? area.risk.default_level : (area ? 'low' : 'unknown'),
+      tags: area && area.risk ? (area.risk.tags || []) : [],
+      reasons: area ? [`area ${area.id}`, `${confidence} confidence`] : ['low confidence; no unique area'],
+    },
+    agentInstructions: agentInstructionsFor(mode),
+    questions: area ? [] : [
+      'No high-confidence area was found. Add aliases/entrypoints to .hive/map/areas.yaml or rerun with --area <id>.',
+    ],
+    explain: {
+      areaScores: scored.slice(0, 8).map((item) => ({
+        id: item.area.id,
+        score: item.score,
+        signals: item.signals.slice(0, 8),
+      })),
+      selectedArea: area ? area.id : null,
+      scopeQuality: scope.quality,
+      relevantFileSources: relevant.map((file) => ({
+        path: file.path,
+        source: file.source,
+        role: file.role || '',
+        reason: file.reason,
+      })),
+      validationQuality: validationPlan.length > 0 ? 'configured' : 'missing',
+      warnings,
+      reviewGated,
+      decompositionSignals: decomposition,
+      candidatePhaseSeeds: phaseSeeds,
+      grepScope: restrictGrepToReadable ? 'readable_scope' : 'repo',
+      recommendedActions: actions,
+    },
+  };
+
+  if (mode === 'needs_decomposition') {
+    packet.splitNote = createSplitNote(root, packet, phaseSeeds, decomposition, options);
+  }
+
+  const contextDir = path.join(hiveDir(root), 'context');
+  ensureDir(contextDir);
+  const jsonPath = path.join(contextDir, `${id}.json`);
+  const mdPath = path.join(contextDir, `${id}.md`);
+  writeJson(jsonPath, packet);
+  writeText(mdPath, buildContextMarkdown(packet));
+  return { packet, jsonPath, mdPath };
+}
+
+module.exports = {
+  buildContextMarkdown,
+  createContextPacket,
+  tokenize,
+};