@haaaiawd/loom 1.1.0 → 1.2.1

package/cli/src/capability-graph.js

@@ -11,6 +11,7 @@ const NODE_KINDS = ['outcome', 'concern', 'capability', 'risk', 'evidence'];
 const NODE_STATUSES = ['open', 'researched', 'covered', 'deferred', 'out_of_scope'];
 const ROUTES = ['expand', 'brief', 'intent', 'defer', 'exclude', 'covered_by'];
 const RELATIONSHIPS = ['refines', 'requires', 'realizes', 'constrains', 'risks', 'validated_by', 'covered_by'];
+const ACQUISITION_MODES = ['adaptive', 'external_required', 'project_only'];
 const VERIFICATION_FIELDS = ['method', 'target', 'procedure', 'pass_criteria', 'artifact'];
 const EVIDENCE_ARTIFACT_DIRS = ['verifications', '08_ASSET_LIBRARY/files'];
 
@@ -66,6 +67,21 @@ function validateNode(id, node, allIds, errors) {
   if (node.asset_refs !== undefined && node.kind !== 'evidence') {
     errors.push(`nodes["${id}"].asset_refs 只允许写在 evidence 节点`);
   }
+  if (node.acquisition_mode !== undefined) {
+    if (node.kind !== 'capability') {
+      errors.push(`nodes["${id}"].acquisition_mode 只允许写在 capability 节点`);
+    } else if (!ACQUISITION_MODES.includes(node.acquisition_mode)) {
+      errors.push(`nodes["${id}"].acquisition_mode 非法: ${node.acquisition_mode}`);
+    }
+  }
+  if (node.acquisition_mode === 'project_only'
+    && (typeof node.acquisition_rationale !== 'string' || !node.acquisition_rationale.trim())) {
+    errors.push(`nodes["${id}"].acquisition_mode=project_only 必须声明 acquisition_rationale`);
+  }
+  if (node.impact === 'high' && node.acquisition_mode === 'adaptive'
+    && (typeof node.acquisition_rationale !== 'string' || !node.acquisition_rationale.trim())) {
+    errors.push(`nodes["${id}"] 为高影响 capability 且选择 adaptive 时必须声明 acquisition_rationale；说明为何此处不启用 external_required`);
+  }
   if (node.verification !== undefined) {
     if (node.kind !== 'evidence') {
       errors.push(`nodes["${id}"].verification 只允许写在 evidence 节点`);
@@ -131,6 +147,13 @@ export function loadCapabilityGraph(versionDir, { required = true } = {}) {
   return validateCapabilityGraph(readJsonFile(filePath, 'Capability Graph'));
 }
 
+function getEffectiveAcquisitionMode(node) {
+  if (node.kind !== 'capability') return null;
+  if (node.acquisition_mode) return node.acquisition_mode;
+  if (node.impact === 'high') return 'external_required';
+  return 'adaptive';
+}
+
 function isRouted(node) {
   return ['brief', 'intent', 'defer', 'exclude', 'covered_by'].includes(node.route);
 }
@@ -248,6 +271,7 @@ export function getCapabilityCoverage(versionDir) {
   const capabilitiesWithoutPlan = [];
   const routingGaps = [];
   const outcomesWithoutConcern = [];
+  const evidenceArtifactGaps = [];
 
   for (const node of nodes) {
     for (const intentId of node.intent_refs || []) {
@@ -261,6 +285,19 @@ export function getCapabilityCoverage(versionDir) {
     if (node.route === 'brief' && !node.brief_ref) {
       capabilitiesWithoutPlan.push({ node_id: node.id, reason: 'route=brief 但缺少 brief_ref' });
     }
+    if (node.kind === 'capability') {
+      const linkedIntents = (node.intent_refs || [])
+        .map((intentId) => intentMap.intents[intentId])
+        .filter(Boolean);
+      const needsExternalAcquisition = linkedIntents.length > 0
+        && getEffectiveAcquisitionMode(node) === 'external_required';
+      if (needsExternalAcquisition && !node.brief_ref && node.route !== 'brief') {
+        capabilitiesWithoutPlan.push({
+          node_id: node.id,
+          reason: '外部能力获取为 required，但缺少 brief_ref 来定义专业问题与验收边界',
+        });
+      }
+    }
     if (['defer', 'exclude'].includes(node.route) && (!node.rationale || typeof node.rationale !== 'string' || node.rationale.trim() === '')) {
       routingGaps.push({ node_id: node.id, reason: `route=${node.route} 但缺少 rationale` });
     }
@@ -273,6 +310,12 @@ export function getCapabilityCoverage(versionDir) {
     if (node.kind === 'outcome' && !(node.relationships || []).some((relation) => graph.nodes[relation.target]?.kind === 'concern')) {
       outcomesWithoutConcern.push({ node_id: node.id, reason: 'outcome 没有连接到 concern，项目初衷尚未展开为问题面' });
     }
+    if (node.kind === 'evidence' && node.verification?.artifact) {
+      const ownedCompletedIntent = (node.intent_refs || []).some((intentId) => intentMap.intents[intentId]?.status === 'completed');
+      if (ownedCompletedIntent && !resolveEvidenceArtifact(versionDir, node.verification.artifact)) {
+        evidenceArtifactGaps.push({ node_id: node.id, reason: `已完成 Intent 的 evidence artifact 不存在或不可读: ${node.verification.artifact}` });
+      }
+    }
     if (node.brief_ref) {
       try { resolveBrief(versionDir, node.brief_ref); } catch (error) {
         capabilitiesWithoutPlan.push({ node_id: node.id, reason: error.message });
@@ -294,6 +337,7 @@ export function getCapabilityCoverage(versionDir) {
       routing_gaps: routingGaps.length,
       outcomes_without_concern: outcomesWithoutConcern.length,
       high_outcomes_without_observable_evidence: highOutcomesWithoutObservableEvidence.length,
+      evidence_artifact_gaps: evidenceArtifactGaps.length,
       intent_mapping_required: intentMappingRequired,
       unmapped_intents: unmappedIntents.length,
       ready: highUnrouted.length === 0
@@ -302,6 +346,7 @@ export function getCapabilityCoverage(versionDir) {
         && routingGaps.length === 0
         && outcomesWithoutConcern.length === 0
         && highOutcomesWithoutObservableEvidence.length === 0
+        && evidenceArtifactGaps.length === 0
         && unmappedIntents.length === 0,
     },
     high_unrouted: highUnrouted,
@@ -310,6 +355,7 @@ export function getCapabilityCoverage(versionDir) {
     routing_gaps: routingGaps,
     outcomes_without_concern: outcomesWithoutConcern,
     high_outcomes_without_observable_evidence: highOutcomesWithoutObservableEvidence,
+    evidence_artifact_gaps: evidenceArtifactGaps,
     unmapped_intents: unmappedIntents,
   };
 }
@@ -339,7 +385,15 @@ function collectCompilationNodes(graph, intentId) {
 
 export function compileCapabilityInputs(versionDir, intentId) {
   const graph = loadCapabilityGraph(versionDir, { required: false });
-  if (!graph) return { available: false, nodes: [], briefs: [], warnings: ['项目尚未建立 Capability Graph；使用 Intent 的 capability_needs 兼容路径。'] };
+  if (!graph) {
+    return {
+      available: false,
+      nodes: [],
+      briefs: [],
+      warnings: ['项目尚未建立 Capability Graph；使用 Intent 的 capability_needs 兼容路径。'],
+      acquisition: { required: false, required_node_ids: [], nodes: [] },
+    };
+  }
   const nodes = collectCompilationNodes(graph, intentId);
   const briefs = [];
   const warnings = [];
@@ -347,5 +401,30 @@ export function compileCapabilityInputs(versionDir, intentId) {
     if (!node.brief_ref) continue;
     try { briefs.push({ node_id: node.id, ...resolveBrief(versionDir, node.brief_ref) }); } catch (error) { warnings.push(`${node.id}: ${error.message}`); }
   }
-  return { available: true, nodes, briefs, warnings };
+  const acquisitionNodes = nodes
+    .filter((node) => node.kind === 'capability')
+    .map((node) => ({
+      node_id: node.id,
+      title: node.title,
+      mode: getEffectiveAcquisitionMode(node),
+      reason: node.acquisition_mode
+        ? 'Capability Graph 显式声明'
+        : node.impact === 'high'
+          ? '高影响能力默认需要外部来源化'
+          : '按任务证据自适应判断',
+    }));
+  const requiredNodeIds = acquisitionNodes
+    .filter((node) => node.mode === 'external_required')
+    .map((node) => node.node_id);
+  return {
+    available: true,
+    nodes,
+    briefs,
+    warnings,
+    acquisition: {
+      required: requiredNodeIds.length > 0,
+      required_node_ids: requiredNodeIds,
+      nodes: acquisitionNodes,
+    },
+  };
 }

package/cli/src/diagnostics.js

@@ -15,6 +15,7 @@ import { getCapabilityCoverage, getCapabilityGraphPath, loadCapabilityGraph } fr
 import { listCapabilityProposals } from './capability-proposals.js';
 import { getAssetManifestPath, validateAssetLibrary } from './asset-library.js';
 import { validateAtelierRecord } from './atelier.js';
+import { getExpertisePackState } from './expertise-pack.js';
 
 function readIntentMapRaw(versionDir) {
   const filePath = join(versionDir, '04_INTENT_MAP.json');
@@ -178,6 +179,8 @@ const FIX_HINTS = {
   asset_library_invalid: '修复 08_ASSET_LIBRARY/manifest.json 的来源、许可、哈希、库内路径或 evidence 双向引用，然后运行 loom asset validate。',
   atelier_record_invalid: '运行 loom atelier init {id} 创建记录，或按校验错误修正后运行 loom atelier validate {id}。',
   atelier_verification_missing: '重新运行独立 Keeper 验证，让 passed 记录绑定当前 Atelier Record 与 stance_revision。',
+  expertise_pack_invalid: '运行 loom expertise init {id}（若尚未创建）；实际执行 find skill / 网络或文档检索，补齐来源与 Capability Capsules 后运行 loom expertise validate {id}。',
+  expertise_verification_missing: '重新运行独立 Keeper 验证，让 passed 记录绑定当前 10_EXPERTISE_PACKS/{id}.json。',
 };
 
 /**
@@ -271,6 +274,9 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
         for (const item of coverage.high_outcomes_without_observable_evidence) {
           issues.push({ id: item.node_id, type: 'capability_outcome_unobservable', severity: 'high', msg: `${item.node_id} 缺少真实呈现或交付的验证入口: ${item.reason}` });
         }
+        for (const item of coverage.evidence_artifact_gaps || []) {
+          issues.push({ id: item.node_id, type: 'capability_evidence_artifact_missing', severity: 'high', msg: `${item.node_id} 的完成证据不可用: ${item.reason}` });
+        }
         for (const item of coverage.orphan_intent_refs) {
           issues.push({ id: item.node_id, type: 'intent_graph_unmapped', severity: 'high', msg: `${item.node_id} 引用了不存在的 Intent: ${item.intent_id}` });
         }
@@ -314,6 +320,33 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
         }
       }
     }
+    if (!['pending', 'blocked', 'deprecated'].includes(intent.status)) {
+      try {
+        const expertise = getExpertisePackState(versionDir, id);
+        if (expertise.required && !expertise.ready) {
+          issues.push({
+            id,
+            type: 'expertise_pack_invalid',
+            severity: intent.status === 'completed' || latest?.verdict === 'passed' ? 'high' : 'medium',
+            msg: `${id} 的外部能力获取强门尚未闭合: ${expertise.reason || 'Expertise Pack not ready'}`,
+          });
+        } else if (expertise.required && latest?.verdict === 'passed') {
+          const validation = expertise.validation;
+          if (latest.expertise?.record_ref !== `10_EXPERTISE_PACKS/${id}.json`
+            || latest.expertise?.intent_revision !== validation.intent_revision
+            || latest.expertise?.source_count !== validation.source_count
+            || latest.expertise?.capsule_count !== validation.capsule_count
+            || latest.expertise?.pack_digest !== validation.pack_digest) {
+            issues.push({
+              id,
+              type: 'expertise_verification_missing',
+              severity: 'high',
+              msg: `${id} 的最新 passed 未绑定当前 Expertise Pack、Intent revision 与来源/Capsule 计数`,
+            });
+          }
+        }
+      } catch { /* Capability Graph 的结构错误已由上方统一报告。 */ }
+    }
     if (intent.quality_strategy === 'atelier' && latest?.verdict === 'passed') {
       const atelier = atelierRecords.get(id);
       if (!atelier

package/cli/src/expertise-pack.js

@@ -0,0 +1,336 @@
+// expertise-pack.js — provenance-backed external capability acquisition for one Intent.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { getIntent } from './intent-map.js';
+import { compileCapabilityInputs } from './capability-graph.js';
+import { getLoomRoot } from './shared/paths.js';
+import { readJsonFile } from './shared/md-utils.js';
+
+const PACKS_DIR = '10_EXPERTISE_PACKS';
+const VALID_STATUS = ['draft', 'ready', 'blocked'];
+const QUERY_CHANNELS = ['skill_registry', 'web', 'official_docs', 'research', 'tool', 'asset'];
+const SOURCE_KINDS = ['skill', 'web', 'official_docs', 'research', 'tool', 'human'];
+const SOURCE_AUTHORITIES = ['official', 'primary', 'expert', 'community', 'secondary'];
+const EXTERNAL_KNOWLEDGE_KINDS = new Set(['skill', 'web', 'official_docs', 'research']);
+
+export function getExpertisePacksDir(versionDir) {
+  return join(versionDir, PACKS_DIR);
+}
+
+export function getExpertisePackPath(versionDir, intentId) {
+  return join(getExpertisePacksDir(versionDir), `${intentId}.json`);
+}
+
+function pushText(value, label, errors) {
+  if (typeof value !== 'string' || value.trim() === '') errors.push(`${label} 必须是非空字符串`);
+}
+
+function pushTextArray(value, label, errors, { min = 1 } = {}) {
+  if (!Array.isArray(value)) {
+    errors.push(`${label} 必须是字符串数组`);
+    return;
+  }
+  if (value.length < min) errors.push(`${label} 至少需要 ${min} 项`);
+  value.forEach((item, index) => pushText(item, `${label}[${index}]`, errors));
+}
+
+function isHttpsLocator(value) {
+  try {
+    return new URL(value).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+export function getExpertiseRequirement(versionDir, intentId) {
+  const intent = getIntent(versionDir, intentId);
+  const compiled = compileCapabilityInputs(versionDir, intentId);
+  const acquisition = compiled.acquisition || {
+    required: false,
+    required_node_ids: [],
+    nodes: [],
+  };
+  return {
+    intent,
+    compiled,
+    required: acquisition.required === true,
+    required_node_ids: acquisition.required_node_ids || [],
+    acquisition_nodes: acquisition.nodes || [],
+  };
+}
+
+function validateSearchPlan(plan, strict, errors) {
+  if (!plan || typeof plan !== 'object' || Array.isArray(plan)) {
+    errors.push('search_plan 必须是对象');
+    return;
+  }
+  if (!strict) return;
+  pushText(plan.decision_question, 'search_plan.decision_question', errors);
+  pushTextArray(plan.project_signals, 'search_plan.project_signals', errors);
+  pushTextArray(plan.constraints, 'search_plan.constraints', errors);
+  pushText(plan.stop_condition, 'search_plan.stop_condition', errors);
+  if (!Array.isArray(plan.derived_queries) || plan.derived_queries.length === 0) {
+    errors.push('search_plan.derived_queries 至少需要一条运行时派生查询');
+  } else {
+    plan.derived_queries.forEach((query, index) => {
+      const prefix = `search_plan.derived_queries[${index}]`;
+      if (!query || typeof query !== 'object' || Array.isArray(query)) {
+        errors.push(`${prefix} 必须是对象`);
+        return;
+      }
+      if (!QUERY_CHANNELS.includes(query.channel)) {
+        errors.push(`${prefix}.channel 必须是 ${QUERY_CHANNELS.join('|')}`);
+      }
+      pushText(query.query, `${prefix}.query`, errors);
+      pushText(query.rationale, `${prefix}.rationale`, errors);
+    });
+  }
+}
+
+function validateSources(sources, strict, errors) {
+  const ids = new Set();
+  const valid = new Map();
+  if (!Array.isArray(sources)) {
+    errors.push('sources 必须是数组');
+    return { ids, valid, externalCount: 0 };
+  }
+  if (strict && sources.length === 0) errors.push('ready Expertise Pack 必须包含外部来源');
+  let externalCount = 0;
+  sources.forEach((source, index) => {
+    const prefix = `sources[${index}]`;
+    if (!source || typeof source !== 'object' || Array.isArray(source)) {
+      errors.push(`${prefix} 必须是对象`);
+      return;
+    }
+    pushText(source.id, `${prefix}.id`, errors);
+    if (typeof source.id === 'string') {
+      if (ids.has(source.id)) errors.push(`${prefix}.id 重复: ${source.id}`);
+      ids.add(source.id);
+    }
+    if (!SOURCE_KINDS.includes(source.kind)) {
+      errors.push(`${prefix}.kind 必须是 ${SOURCE_KINDS.join('|')}`);
+    }
+    if (!SOURCE_AUTHORITIES.includes(source.authority)) {
+      errors.push(`${prefix}.authority 必须是 ${SOURCE_AUTHORITIES.join('|')}`);
+    }
+    pushText(source.title, `${prefix}.title`, errors);
+    pushText(source.locator, `${prefix}.locator`, errors);
+    if (source.kind !== 'human' && typeof source.locator === 'string' && !isHttpsLocator(source.locator)) {
+      errors.push(`${prefix}.locator 必须是可追溯的 https URL`);
+    }
+    pushText(source.retrieved_at, `${prefix}.retrieved_at`, errors);
+    if (typeof source.retrieved_at === 'string' && Number.isNaN(Date.parse(source.retrieved_at))) {
+      errors.push(`${prefix}.retrieved_at 必须是合法日期时间`);
+    }
+    pushText(source.why_selected, `${prefix}.why_selected`, errors);
+    pushText(source.retrieval_evidence, `${prefix}.retrieval_evidence`, errors);
+    if (EXTERNAL_KNOWLEDGE_KINDS.has(source.kind)) externalCount += 1;
+    if (typeof source.id === 'string' && source.id.trim()) valid.set(source.id, source);
+  });
+  if (strict && externalCount === 0) {
+    errors.push('ready Expertise Pack 至少需要一个 skill|web|official_docs|research 外部知识来源');
+  }
+  return { ids, valid, externalCount };
+}
+
+function validateCapsules(capsules, requiredNodeIds, sourceMap, strict, errors) {
+  const covered = new Set();
+  if (!Array.isArray(capsules)) {
+    errors.push('capsules 必须是数组');
+    return covered;
+  }
+  if (strict && capsules.length === 0) errors.push('ready Expertise Pack 必须包含 Capability Capsule');
+  capsules.forEach((capsule, index) => {
+    const prefix = `capsules[${index}]`;
+    if (!capsule || typeof capsule !== 'object' || Array.isArray(capsule)) {
+      errors.push(`${prefix} 必须是对象`);
+      return;
+    }
+    pushText(capsule.capability_ref, `${prefix}.capability_ref`, errors);
+    if (typeof capsule.capability_ref === 'string') covered.add(capsule.capability_ref);
+    if (strict && requiredNodeIds.length > 0 && !requiredNodeIds.includes(capsule.capability_ref)) {
+      errors.push(`${prefix}.capability_ref 未引用当前 Intent 的外部获取能力节点: ${capsule.capability_ref}`);
+    }
+    if (!strict) return;
+    pushText(capsule.professional_problem, `${prefix}.professional_problem`, errors);
+    pushText(capsule.when_to_use, `${prefix}.when_to_use`, errors);
+    pushTextArray(capsule.rules, `${prefix}.rules`, errors);
+    pushTextArray(capsule.workflow, `${prefix}.workflow`, errors);
+    pushTextArray(capsule.decision_gates, `${prefix}.decision_gates`, errors);
+    pushTextArray(capsule.failure_modes, `${prefix}.failure_modes`, errors);
+    pushTextArray(capsule.verification_signals, `${prefix}.verification_signals`, errors);
+    if (!Array.isArray(capsule.source_refs) || capsule.source_refs.length === 0) {
+      errors.push(`${prefix}.source_refs 至少需要一个来源`);
+    } else {
+      let externalRefCount = 0;
+      capsule.source_refs.forEach((ref, refIndex) => {
+        pushText(ref, `${prefix}.source_refs[${refIndex}]`, errors);
+        if (typeof ref === 'string' && !sourceMap.has(ref)) {
+          errors.push(`${prefix}.source_refs[${refIndex}] 引用不存在的来源: ${ref}`);
+        } else if (EXTERNAL_KNOWLEDGE_KINDS.has(sourceMap.get(ref)?.kind)) {
+          externalRefCount += 1;
+        }
+      });
+      if (externalRefCount === 0) {
+        errors.push(`${prefix} 必须直接引用至少一个 skill|web|official_docs|research 外部知识来源`);
+      }
+    }
+  });
+  if (strict) {
+    for (const nodeId of requiredNodeIds) {
+      if (!covered.has(nodeId)) errors.push(`缺少外部必需能力 ${nodeId} 的 Capability Capsule`);
+    }
+  }
+  return covered;
+}
+
+export function validateExpertisePack(versionDir, intentId, pack = null, { requireReady = true } = {}) {
+  const requirement = getExpertiseRequirement(versionDir, intentId);
+  const path = getExpertisePackPath(versionDir, intentId);
+  const data = pack ?? readJsonFile(path, 'Expertise Pack');
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error('Expertise Pack 校验失败:\n  - 根节点必须是对象');
+  }
+  const errors = [];
+  if (!data._meta || typeof data._meta !== 'object' || Array.isArray(data._meta)) {
+    errors.push('_meta 必须是对象');
+  } else {
+    if (data._meta._version !== '1.0') errors.push('_meta._version 必须是 1.0');
+    if (data._meta._loom_version !== basename(versionDir)) {
+      errors.push(`_meta._loom_version 必须是 ${basename(versionDir)}`);
+    }
+  }
+  if (data.intent_id !== intentId) errors.push(`intent_id 必须是 ${intentId}`);
+  if (data.intent_revision !== (requirement.intent.revision ?? 1)) {
+    errors.push(`intent_revision=${data.intent_revision} 已过期；当前为 ${requirement.intent.revision ?? 1}`);
+  }
+  if (!Array.isArray(data.required_capability_refs)) {
+    errors.push('required_capability_refs 必须是数组');
+  } else {
+    data.required_capability_refs.forEach((ref, index) => {
+      pushText(ref, `required_capability_refs[${index}]`, errors);
+    });
+    const declared = [...new Set(data.required_capability_refs)].sort();
+    const expected = [...new Set(requirement.required_node_ids)].sort();
+    if (JSON.stringify(declared) !== JSON.stringify(expected)) {
+      errors.push(`required_capability_refs 必须精确匹配当前强门节点: ${expected.join(', ') || '无'}`);
+    }
+  }
+  if (!VALID_STATUS.includes(data.status)) errors.push(`status 必须是 ${VALID_STATUS.join('|')}`);
+  const strict = data.status === 'ready';
+  validateSearchPlan(data.search_plan, data.status === 'ready' || data.status === 'blocked', errors);
+  const sourceResult = validateSources(data.sources, strict, errors);
+  validateCapsules(data.capsules, requirement.required_node_ids, sourceResult.valid, strict, errors);
+  if (data.status === 'blocked') {
+    if (!data.blocker || typeof data.blocker !== 'object' || Array.isArray(data.blocker)) {
+      errors.push('blocked 状态必须提供 blocker 对象');
+    } else {
+      pushText(data.blocker.reason, 'blocker.reason', errors);
+      pushText(data.blocker.recovery_condition, 'blocker.recovery_condition', errors);
+    }
+  } else if (data.blocker !== null && data.blocker !== undefined) {
+    errors.push('非 blocked 状态的 blocker 必须为 null 或省略');
+  }
+  if (requireReady && requirement.required && data.status !== 'ready') {
+    errors.push(`当前 Intent 需要外部能力获取，Expertise Pack 必须为 ready（当前: ${data.status}）`);
+  }
+  if (errors.length) throw new Error(`Expertise Pack 校验失败:\n  - ${errors.join('\n  - ')}`);
+  return {
+    valid: true,
+    required: requirement.required,
+    intent_id: intentId,
+    intent_revision: data.intent_revision,
+    status: data.status,
+    required_node_ids: requirement.required_node_ids,
+    source_count: data.sources.length,
+    external_source_count: sourceResult.externalCount,
+    capsule_count: data.capsules.length,
+    pack_digest: createHash('sha256').update(JSON.stringify(data)).digest('hex'),
+    path,
+  };
+}
+
+export function getExpertisePack(versionDir, intentId) {
+  const path = getExpertisePackPath(versionDir, intentId);
+  if (!existsSync(path)) throw new Error(`Expertise Pack 不存在: ${path}`);
+  const pack = readJsonFile(path, 'Expertise Pack');
+  validateExpertisePack(versionDir, intentId, pack, { requireReady: false });
+  return pack;
+}
+
+export function initExpertisePack(versionDir, intentId) {
+  const requirement = getExpertiseRequirement(versionDir, intentId);
+  if (!requirement.required) {
+    throw new Error(`${intentId} 当前没有外部能力获取强门；只有显式 external_required 或未显式豁免的高影响 capability 才需要持久化 Expertise Pack`);
+  }
+  const path = getExpertisePackPath(versionDir, intentId);
+  if (existsSync(path)) throw new Error(`Expertise Pack 已存在，不会覆盖: ${path}`);
+  const templatePath = join(getLoomRoot(), 'templates', 'EXPERTISE_PACK_TEMPLATE.json');
+  const pack = JSON.parse(readFileSync(templatePath, 'utf-8'));
+  pack._meta._loom_version = basename(versionDir);
+  pack.intent_id = intentId;
+  pack.intent_revision = requirement.intent.revision ?? 1;
+  pack.required_capability_refs = requirement.required_node_ids;
+  mkdirSync(getExpertisePacksDir(versionDir), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(pack, null, 2)}\n`, { encoding: 'utf-8', flag: 'wx' });
+  return pack;
+}
+
+export function getExpertisePackState(versionDir, intentId) {
+  const requirement = getExpertiseRequirement(versionDir, intentId);
+  const path = getExpertisePackPath(versionDir, intentId);
+  if (!requirement.required) {
+    return { required: false, ready: true, path, required_node_ids: [] };
+  }
+  if (!existsSync(path)) {
+    return { required: true, ready: false, path, required_node_ids: requirement.required_node_ids, reason: 'missing' };
+  }
+  try {
+    const validation = validateExpertisePack(versionDir, intentId, null, { requireReady: false });
+    const ready = validation.status === 'ready';
+    const pack = ready ? null : readJsonFile(path, 'Expertise Pack');
+    const reason = ready
+      ? undefined
+      : validation.status === 'blocked'
+        ? `blocked: ${pack.blocker.reason}`
+        : `status=${validation.status}`;
+    return { required: true, ready, path, required_node_ids: requirement.required_node_ids, validation, reason };
+  } catch (error) {
+    return { required: true, ready: false, path, required_node_ids: requirement.required_node_ids, reason: error.message };
+  }
+}
+
+export function assertExpertiseReady(versionDir, intentId) {
+  const state = getExpertisePackState(versionDir, intentId);
+  if (!state.required) return null;
+  if (!state.ready) {
+    const action = state.reason === 'missing'
+      ? `先运行 loom expertise init ${intentId}，通过 find skill 与网络搜索获取外部信息，完成后运行 loom expertise validate ${intentId}`
+      : `修正 10_EXPERTISE_PACKS/${intentId}.json 后运行 loom expertise validate ${intentId}`;
+    throw new Error(`${intentId} 的外部能力获取强门尚未闭合: ${state.reason || 'Expertise Pack not ready'}\n${action}`);
+  }
+  return state.validation;
+}
+
+export function formatExpertisePackForPrompt(pack) {
+  const lines = [
+    `- decision_question: ${pack.search_plan.decision_question}`,
+    `- sources: ${pack.sources.map((source) => `${source.id} ${source.title} (${source.locator})`).join('; ')}`,
+  ];
+  for (const capsule of pack.capsules) {
+    lines.push(
+      `\n### Capability Capsule: ${capsule.capability_ref}`,
+      `- professional_problem: ${capsule.professional_problem}`,
+      `- when_to_use: ${capsule.when_to_use}`,
+      `- rules:\n${capsule.rules.map((item) => `  - ${item}`).join('\n')}`,
+      `- workflow:\n${capsule.workflow.map((item) => `  - ${item}`).join('\n')}`,
+      `- decision_gates:\n${capsule.decision_gates.map((item) => `  - ${item}`).join('\n')}`,
+      `- failure_modes:\n${capsule.failure_modes.map((item) => `  - ${item}`).join('\n')}`,
+      `- verification_signals:\n${capsule.verification_signals.map((item) => `  - ${item}`).join('\n')}`,
+      `- source_refs: ${capsule.source_refs.join(', ')}`,
+    );
+  }
+  return lines.join('\n');
+}

package/cli/src/guide.js

@@ -10,6 +10,7 @@ import { getCapabilityCoverage } from './capability-graph.js';
 import { listCapabilityProposals } from './capability-proposals.js';
 import { isAutoOn, getAutoMode, writeHeartbeat, needsHumanReview } from './auto.js';
 import { doctor } from './diagnostics.js';
+import { getExpertisePackState } from './expertise-pack.js';
 
 /**
  * 检测文件是否还是模板（未填充真实内容）。
@@ -145,7 +146,7 @@ export function guideProject(projectDir, options = {}) {
     }
   } else if (result.stage_num >= 4) {
     if (auto) {
-      result.message += '\n\n> AUTO 模式开启——直接执行 next_command，无需人类确认。';
+      result.message += '\n\n> AUTO 模式开启——可继续进入下一阶段；契约、证据与 Keeper 门禁仍不会被跳过。';
     } else {
       result.message += '\n\n> ⚠ AUTO 模式关闭——执行 next_command 后等人类确认再继续。';
     }
@@ -373,6 +374,39 @@ function diagnoseStage(cwd, loomRoot, auto) {
   // 状态 5: 有 in_progress
   if (counts.in_progress > 0) {
     const inProgressIds = allIntents.filter((i) => i.status === 'in_progress').map((i) => i.id);
+    const expertiseOpen = allIntents
+      .filter((intent) => intent.status === 'in_progress')
+      .map((intent) => ({ intent, state: getExpertisePackState(versionDir, intent.id) }))
+      .find(({ state }) => state.required && !state.ready);
+    if (expertiseOpen) {
+      const missing = expertiseOpen.state.reason === 'missing';
+      const blocked = expertiseOpen.state.reason?.startsWith('blocked:');
+      return {
+        stage: 'in_loop',
+        stage_num: 5,
+        details: {
+          version: current,
+          counts,
+          in_progress_ids: inProgressIds,
+          expertise_intent: expertiseOpen.intent.id,
+          expertise_reason: expertiseOpen.state.reason,
+        },
+        auto,
+        next_action: missing
+          ? '创建搜索计划并执行外部能力获取'
+          : blocked
+            ? '解决 Expertise Pack 记录的外部获取阻塞'
+            : '补齐来源化 Expertise Pack',
+        next_command: missing
+          ? `loom expertise init ${expertiseOpen.intent.id}`
+          : blocked
+            ? `loom expertise get ${expertiseOpen.intent.id}`
+            : `loom expertise validate ${expertiseOpen.intent.id}`,
+        message: blocked
+          ? `${expertiseOpen.intent.id} 的外部能力获取已明确 blocked：${expertiseOpen.state.reason.slice('blocked: '.length)}。满足 Pack 中的 recovery_condition 后再继续；不能让模型补齐空白。`
+          : `${expertiseOpen.intent.id} 需要外部能力获取。先由任务信号派生搜索词，实际使用 find skill、网络搜索、官方文档或研究资料，再把可回查来源编译为 Capability Capsules；模型临时生成内容不能代替来源。`,
+      };
+    }
     const atelierWithoutRecord = allIntents.find((intent) => intent.status === 'in_progress'
       && intent.quality_strategy === 'atelier'
       && !existsSync(join(versionDir, '09_ATELIER', `${intent.id}.json`)));

package/cli/src/init.js

@@ -51,7 +51,8 @@ export function createVersionStructure(projectDir, version, parentVersion = null
     `.loom/${v}/07_CAPABILITY_BRIEFS`,
     `.loom/${v}/07_GRAPH_PROPOSALS`,
     `.loom/${v}/08_ASSET_LIBRARY/files`,
-  ];
+    `.loom/${v}/10_EXPERTISE_PACKS`,
+  ];
 
   for (const d of dirs) {
     const path = join(cwd, d);
@@ -168,6 +169,7 @@ export function initProject(projectDir) {
       '3. 只在当前角色的权限内行动；发现目标、契约或架构需要改变时，按 LOOM 回流，不要静默扩展范围。',
       '4. 完成前运行当前 Intent 的验证方法与 `loom doctor`；声称质量提升时必须提供基线相对 Quality Proof，以磁盘证据而非会话记忆判断状态。',
       '5. Keeper 验证必须运行在新的 Agent thread 中；同一会话切换角色不构成独立验证。',
+      '6. 协作节奏默认是手动；需要让 Agent 在已允许阶段连续推进时，显式运行 `loom auto on`。AUTO 不会跳过契约、证据或 Keeper 门禁。',
       '',
       '常用入口：',
       '- `loom --help`',