hive-lite 0.1.3 → 0.1.7

package/src/lib/map.js

@@ -331,10 +331,14 @@ function summarizeFindContext(context) {
     },
     warnings: context.warnings || [],
     reviewGated: context.reviewGated || (context.explain && context.explain.reviewGated) || [],
+    writePlan: context.writePlan || (context.explain && context.explain.writePlan) || null,
     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 || [],
+    selectedWritableScope: context.writableScope || [],
+    writableExisting: scope.writableExisting || [],
+    writableCreatePatterns: scope.writableCreatePatterns || [],
     writableConditional: scope.writableConditional || [],
     writableBroadFallback: scope.writableBroadFallback || [],
     forbidden: scope.forbidden || context.doNotTouch || [],
@@ -431,6 +435,12 @@ function repairFocusFromFind(findContext, userFocus) {
   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_DIRECT_NEW_FILE_SCOPE')) goals.push('add narrow writable_direct patterns or exact paths for the new peer files this intent must create');
+  if (warnings.includes('DIRECT_ONLY_REFERENCE_PEERS')) goals.push('move peer examples out of selected direct scope and add target create capability');
+  if (warnings.includes('BROAD_FALLBACK_ONLY')) goals.push('replace broad fallback-only coverage with narrow direct create capability');
+  if (warnings.includes('TARGET_ENTITY_MISMATCH')) goals.push('add direct scope for the requested target identity or mark old peers as references');
+  if (warnings.includes('MISSING_ARTIFACT_FAMILY_SCOPE')) goals.push('add writable_create_patterns for required artifact families');
+  if (warnings.includes('MISSING_REQUIRED_HOOK_SCOPE')) goals.push('add writable_existing hook files required by the artifact family');
   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');
@@ -464,6 +474,15 @@ function findContextPromptSection(findContext) {
     'Review-gated scope from find:',
     ...listLines(findContext.reviewGated, (notice) => `- ${notice.code}: ${notice.message}`),
     '',
+    ...(findContext.writePlan ? [
+      'Write plan from find:',
+      ...listLines(findContext.writePlan.hypotheses || [], (item) => `- ${item.action} ${item.artifactFamily}: ${item.operation}${item.targetIdentity ? ` for ${item.targetIdentity}` : ''}`),
+      'Write plan blocking warnings:',
+      ...listLines(findContext.writePlan.blockingWarnings || [], (item) => `- ${item.code}: ${item.message}`),
+      'Reference files from write plan:',
+      ...listLines(findContext.writePlan.referenceFiles || [], (file) => `- ${file.path}: ${file.reason || ''}`),
+      '',
+    ] : []),
     '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(', ')})` : '';
@@ -476,6 +495,15 @@ function findContextPromptSection(findContext) {
     'Current direct writable scope:',
     ...listLines(findContext.writableDirect, patternLine),
     '',
+    'Selected direct writable scope for this intent:',
+    ...listLines(findContext.selectedWritableScope, patternLine),
+    '',
+    'Current writable existing scope:',
+    ...listLines(findContext.writableExisting, patternLine),
+    '',
+    'Current writable create patterns:',
+    ...listLines(findContext.writableCreatePatterns, patternLine),
+    '',
     'Current conditional writable scope:',
     ...listLines(findContext.writableConditional, patternLine),
     '',
@@ -541,6 +569,9 @@ function buildMapPrompt(result) {
     '- 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.',
+    '- Prefer `writable_existing` for exact update targets and `writable_create_patterns` for new peer files when a repo has create/update distinctions.',
+    '- Put copy sources and peer examples under `readable_reference`, not under selected Direct Writable for new peer intents.',
+    '- Use `artifact_families` to declare required create artifacts and hook files for provider/adapter/endpoint families.',
     '- 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`.',
@@ -594,8 +625,27 @@ function buildMapPrompt(result) {
     '    scope:',
     '      readable:',
     '        - path/to/read/**',
+    '      readable_reference:',
+    '        peer_examples:',
+    '          - path: path/to/ExistingPeer.ts',
+    '            artifact: service_impl',
+    '            peer_identity: Existing',
     '      writable_direct:',
     '        - path/to/real/file.ts',
+    '      writable_existing:',
+    '        - path: path/to/Registry.ts',
+    '          artifact: registry_hook',
+    '          operations:',
+    '            - update_existing',
+    '          required_when:',
+    '            - add_provider_proxy',
+    '      writable_create_patterns:',
+    '        - pattern: path/to/*Provider.ts',
+    '          artifact: service_impl',
+    '          operations:',
+    '            - create_file',
+    '          intent_kinds:',
+    '            - add_provider_proxy',
     '      writable_conditional:',
     '        - pattern: path/to/shared/**',
     '          reason: only if shared model changes are required',
@@ -623,6 +673,19 @@ function buildMapPrompt(result) {
     '      default_level: low',
     '      tags:',
     '        - ui',
+    '    artifact_families:',
+    '      provider_proxy:',
+    '        trigger_terms:',
+    '          en:',
+    '            - provider',
+    '            - proxy',
+    '          zh:',
+    '            - 提供商',
+    '            - 代理',
+    '        create_requires:',
+    '          - service_impl',
+    '        hooks:',
+    '          - registry_hook',
     '```',
     '',
     'Validation profile schema example:',

package/src/lib/next.js

@@ -162,21 +162,21 @@ function applySkillPreflight(root, options, current) {
     ...current,
     phaseGuess: 'skill_preflight',
     primaryAction: action({
-      kind: 'install_operator_skill',
-      label: `Install ${preflight.requiredSkill}`,
-      command: preflight.installCommand,
-      explanation: 'The recommended next operator step requires this Hive Lite skill in the selected agent target.',
+      kind: 'sync_operator_skill',
+      label: `Sync ${preflight.requiredSkill}`,
+      command: preflight.syncCommand,
+      explanation: 'The recommended next operator step requires a current Hive Lite skill in the selected agent target.',
     }),
     secondaryActions: [
       action({
         ...blockedAction,
         enabled: false,
-        disabledReason: `Install ${preflight.requiredSkill} first for the selected agent target.`,
+        disabledReason: `Sync ${preflight.requiredSkill} first for the selected agent target.`,
       }),
       ...current.secondaryActions,
     ],
-    summaryForHuman: `需要先安装 ${preflight.requiredSkill}，然后再继续 Hive Lite operator flow。`,
-    summaryForAgent: `The selected agent target is missing ${preflight.requiredSkill}. Run skills install before using the handoff skill.`,
+    summaryForHuman: `需要先同步 ${preflight.requiredSkill}，然后再继续 Hive Lite operator flow。`,
+    summaryForAgent: `The selected agent target is missing or has a stale ${preflight.requiredSkill}. Run skills sync before using the handoff skill.`,
     operatorSkillPreflight: preflight,
   };
 }
@@ -238,10 +238,10 @@ function evaluateNextAction(cwd, options = {}) {
       kind: 'run_bootstrap_skill',
       label: 'Use hive-lite-bootstrap',
       prompt: bootstrapPrompt(),
-      explanation: 'This git repository has not been initialized for Hive Lite. Use the bootstrap skill to initialize, build the first Project Map, and prepare the setup/map commit before product work starts.',
+      explanation: 'This git repository is missing required Hive Lite setup files. Use the bootstrap skill to initialize or repair setup, build the first Project Map when needed, and prepare the setup/map commit before product work starts.',
     });
-    summaryForHuman = '当前项目还没有初始化 Hive Lite。建议使用 hive-lite-bootstrap 完成首次接入：初始化、建立第一版 Project Map，并在开始第一个需求前准备 setup/map 提交。';
-    summaryForAgent = 'Hive Lite is not initialized. Stop ordinary start/finish/map-maintainer workflows and hand off to hive-lite-bootstrap.';
+    summaryForHuman = '当前项目缺少 Hive Lite setup 文件。建议使用 hive-lite-bootstrap 完成首次接入或 setup 修复，并在开始第一个需求前准备 setup/map 提交。';
+    summaryForAgent = 'Hive Lite setup is missing or incomplete. Stop ordinary start/finish/map-maintainer workflows and hand off to hive-lite-bootstrap.';
   } else if (!workspace.canStartNewRequirement) {
     if (workspace.hive.state === 'in_progress') {
       phaseGuess = 'finish';

package/src/lib/risk.js

@@ -54,6 +54,11 @@ function evaluateChangeRisk(change, map) {
   if (change.scope.status === 'violation') {
     blockingReasons.push(`scope violation: ${change.scope.violations.join(', ')}`);
   }
+  if (change.writePlanStatus && change.writePlanStatus.status === 'blocked') {
+    for (const reason of change.writePlanStatus.blockingReasons || []) {
+      blockingReasons.push(`write plan blocked: ${reason}`);
+    }
+  }
 
   const status = validationStatus(change);
   if (status === 'failed') blockingReasons.push('validation failed');

package/src/lib/scope.js

@@ -12,6 +12,12 @@ function patternFrom(value) {
   return normalizePath((value.pattern || value.path || '').trim());
 }
 
+function arrayFrom(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || '')).filter(Boolean);
+  if (value == null || value === '') return [];
+  return [String(value)];
+}
+
 function normalizePattern(value, defaults = {}) {
   const pattern = patternFrom(value);
   if (!pattern) return null;
@@ -22,6 +28,13 @@ function normalizePattern(value, defaults = {}) {
       requiresReview: defaults.requiresReview === true,
       source: defaults.source || 'map',
       matchCount: defaults.matchCount == null ? null : defaults.matchCount,
+      artifact: defaults.artifact || null,
+      artifactFamily: defaults.artifactFamily || null,
+      operations: arrayFrom(defaults.operations),
+      targetIdentity: defaults.targetIdentity || null,
+      targetSlot: defaults.targetSlot || null,
+      intentKinds: arrayFrom(defaults.intentKinds),
+      requiredWhen: arrayFrom(defaults.requiredWhen),
     };
   }
   return {
@@ -30,6 +43,13 @@ function normalizePattern(value, defaults = {}) {
     requiresReview: value.requires_review === true || value.requiresReview === true || defaults.requiresReview === true,
     source: value.source || defaults.source || 'map',
     matchCount: value.matchCount == null ? (defaults.matchCount == null ? null : defaults.matchCount) : value.matchCount,
+    artifact: value.artifact || defaults.artifact || null,
+    artifactFamily: value.artifact_family || value.artifactFamily || defaults.artifactFamily || null,
+    operations: arrayFrom(value.operations || value.operation || defaults.operations),
+    targetIdentity: value.target_identity || value.targetIdentity || value.peer_identity || value.peerIdentity || defaults.targetIdentity || null,
+    targetSlot: value.target_slot || value.targetSlot || defaults.targetSlot || null,
+    intentKinds: arrayFrom(value.intent_kinds || value.intentKinds || defaults.intentKinds),
+    requiredWhen: arrayFrom(value.required_when || value.requiredWhen || defaults.requiredWhen),
   };
 }
 
@@ -93,29 +113,119 @@ function splitDirectAndBroad(root, values, defaults = {}) {
   return { direct, broad };
 }
 
+function splitItemsAndBroad(root, values, defaults = {}) {
+  const direct = [];
+  const broad = [];
+  for (const value of values || []) {
+    const pattern = patternFrom(value);
+    if (!pattern) continue;
+    const classification = isBroadPattern(root, pattern);
+    const item = normalizePattern(value, {
+      ...defaults,
+      matchCount: classification.matchCount,
+    });
+    if (!item) continue;
+    if (classification.broad) {
+      broad.push({
+        ...item,
+        reason: item.reason || classification.reason || 'broad writable scope',
+        requiresReview: true,
+      });
+    } else {
+      direct.push(item);
+    }
+  }
+  return { direct, broad };
+}
+
+function flattenReferenceValues(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'object' && (value.path || value.pattern)) return [value];
+  if (typeof value === 'object') {
+    return Object.values(value).flatMap((item) => flattenReferenceValues(item));
+  }
+  return [value];
+}
+
+function normalizeReference(value, defaults = {}) {
+  const pattern = patternFrom(value);
+  if (!pattern) return null;
+  if (typeof value === 'string') {
+    return {
+      path: pattern,
+      reason: defaults.reason || '',
+      role: defaults.role || 'reference',
+      artifact: defaults.artifact || null,
+      artifactFamily: defaults.artifactFamily || null,
+      peerIdentity: defaults.peerIdentity || null,
+      source: defaults.source || 'readable_reference',
+    };
+  }
+  return {
+    path: pattern,
+    reason: value.reason || defaults.reason || '',
+    role: value.role || defaults.role || 'reference',
+    artifact: value.artifact || defaults.artifact || null,
+    artifactFamily: value.artifact_family || value.artifactFamily || defaults.artifactFamily || null,
+    peerIdentity: value.peer_identity || value.peerIdentity || value.provider || defaults.peerIdentity || null,
+    source: value.source || defaults.source || 'readable_reference',
+  };
+}
+
+function normalizeReferenceList(value, defaults = {}) {
+  return flattenReferenceValues(value).map((item) => normalizeReference(item, defaults)).filter(Boolean);
+}
+
 function normalizeAreaScope(root, area = {}) {
   const configured = area.scope || {};
   const readable = (configured.readable || area.readable_scope || []).map(patternFrom).filter(Boolean);
+  const readableReference = normalizeReferenceList(configured.readable_reference || area.readable_reference || [], {
+    source: 'readable_reference',
+  });
   const forbidden = (configured.forbidden || area.do_not_touch || []).map(patternFrom).filter(Boolean);
 
   const directValues = configured.writable_direct || [];
+  const existingValues = configured.writable_existing || [];
+  const createValues = configured.writable_create_patterns || [];
   const conditionalValues = configured.writable_conditional || [];
   const broadValues = configured.writable_broad_fallback || [];
   const legacyWritable = !area.scope ? (area.writable_scope || []) : [];
 
-  const directSplit = splitDirectAndBroad(root, directValues, { source: 'writable_direct' });
+  const directSplit = splitItemsAndBroad(root, directValues, { source: 'writable_direct' });
+  const existingSplit = splitItemsAndBroad(root, existingValues, {
+    source: 'writable_existing',
+    operations: ['update_existing'],
+  });
+  const createSplit = splitItemsAndBroad(root, createValues, {
+    source: 'writable_create_patterns',
+    operations: ['create_file'],
+  });
   const legacySplit = splitDirectAndBroad(root, legacyWritable, {
     source: 'legacy_writable_scope',
     reason: 'legacy writable_scope is broad; move this to scope.writable_broad_fallback or add writable_direct',
   });
 
-  const writableDirect = [...directSplit.direct, ...legacySplit.direct];
+  const legacyDirectItems = legacySplit.direct.map((pattern) => normalizePattern(pattern, {
+    source: 'legacy_writable_scope',
+  })).filter(Boolean);
+  const writableDirectItems = [
+    ...directSplit.direct,
+    ...existingSplit.direct,
+    ...createSplit.direct,
+    ...legacyDirectItems,
+  ];
+  const writableDirect = writableDirectItems.map((item) => item.pattern);
+  const writableExisting = existingSplit.direct;
+  const writableCreatePatterns = createSplit.direct;
   const writableConditional = normalizePatternList(conditionalValues, {
     source: 'writable_conditional',
     requiresReview: true,
   });
   const writableBroadFallback = [
     ...directSplit.broad,
+    ...existingSplit.broad,
+    ...createSplit.broad,
     ...normalizePatternList(broadValues, {
       source: 'writable_broad_fallback',
       requiresReview: true,
@@ -139,7 +249,11 @@ function normalizeAreaScope(root, area = {}) {
 
   return {
     readable,
+    readableReference,
     writableDirect,
+    writableDirectItems,
+    writableExisting,
+    writableCreatePatterns,
     writableConditional,
     writableBroadFallback,
     forbidden,
@@ -164,5 +278,6 @@ module.exports = {
   itemPattern,
   normalizeAreaScope,
   normalizePatternList,
+  normalizeReferenceList,
   patternDisplay,
 };

package/src/lib/skills.js

@@ -215,11 +215,11 @@ function targetSelection(options = {}, command = 'doctor') {
   };
 }
 
-function installCommandForOptions(options = {}) {
-  if (options.path && options.path !== true) return `hive-lite skills install --path ${options.path}`;
-  if (options.agent && options.agent !== true) return `hive-lite skills install --agent ${options.agent}`;
-  if (options.all) return 'hive-lite skills install --agent all';
-  return 'hive-lite skills install --agent <codex|claude|gemini>';
+function syncCommandForOptions(options = {}) {
+  if (options.path && options.path !== true) return `hive-lite skills sync --path ${options.path}`;
+  if (options.agent && options.agent !== true) return `hive-lite skills sync --agent ${options.agent}`;
+  if (options.all) return 'hive-lite skills sync --agent all';
+  return 'hive-lite skills sync --agent all';
 }
 
 function skillPreflight(cwd, skillName, options = {}) {
@@ -246,7 +246,7 @@ function skillPreflight(cwd, skillName, options = {}) {
     requiredSkill: skillName,
     targetSelection: targetSelection(options, 'doctor'),
     ready: targets.length > 0 && targets.every((target) => target.status === 'current'),
-    installCommand: installCommandForOptions(options),
+    syncCommand: syncCommandForOptions(options),
     targets,
   };
 }

package/src/lib/status.js

@@ -226,8 +226,8 @@ function actionsFor(state, latestId, diffMatches) {
   }
   if (state === 'hive_init_required') {
     return [
-      action('run_hive_init', 'Run Hive Lite init', 'hive-lite init', 'Initialize Hive Lite setup files before using Hive Lite skills.'),
-      action('stop', 'Stop', null, 'Do not run start, finish, or map-maintainer skills until Hive Lite has been initialized.'),
+      action('run_bootstrap_skill', 'Use hive-lite-bootstrap', '$hive-lite-bootstrap', 'Use the first-time setup or setup repair skill before ordinary start, finish, or map-maintainer workflows.'),
+      action('stop', 'Stop', null, 'Do not run start, finish, or map-maintainer skills until Hive Lite setup is complete.'),
     ];
   }
   if (state === 'clean') {
@@ -314,7 +314,7 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
 
   if (!initialized) {
     state = 'hive_init_required';
-    reason = 'Hive Lite is not initialized in this git repository. Use $hive-lite-bootstrap for first-time setup, or run hive-lite init as the low-level fallback.';
+    reason = 'Hive Lite setup is missing or incomplete in this git repository. Use $hive-lite-bootstrap for first-time setup or setup repair.';
   } else if (dirty && latest.change) {
     if (accepted(latest.change) && !committed(latest.change) && diffMatches) {
       state = 'accepted_uncommitted';