@haaaiawd/loom 1.0.0 → 1.2.0

package/cli/src/diagnostics.js

@@ -11,6 +11,11 @@ import { validatePatches } from './patch.js';
 import { formatIntentRef } from './shared/intent-ref.js';
 import { commandCoversVerificationMethod, getIntentVerificationMethod } from './shared/verification-method.js';
 import { resolveQualityProofReference } from './shared/proof-reference.js';
+import { getCapabilityCoverage, getCapabilityGraphPath, loadCapabilityGraph } from './capability-graph.js';
+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');
@@ -161,7 +166,22 @@ const FIX_HINTS = {
   preservation_dimension_missing: '为 continuity_required 的 Intent 补写并通过 preservation_achievement，证据必须覆盖旧状态到新操作后的完整序列',
   patch_changelog_invalid: '运行 loom patch validate 查看具体错误；修正 06_CHANGELOG.json 后重新生成 Markdown 投影',
   patch_projection_drift: '不要手工编辑 06_CHANGELOG.md；重新运行 loom init 或下一次 loom patch record 生成投影',
-};
+  capability_graph_missing: '这是 1.0 项目的兼容提示；迁移时运行 loom activate architect，创建 07_CAPABILITY_GRAPH.json 并路由高影响节点',
+  capability_graph_template: '运行 loom activate architect，先将愿景展开为 Capability Graph，再创建或修订 Intent Map',
+  capability_graph_invalid: '修正 07_CAPABILITY_GRAPH.json 的节点、关系或枚举值后运行 loom capability coverage',
+  capability_frontier_open: '为高影响节点继续展开、创建 Capability Brief、编译为 Intent，或明确延后/排除理由',
+  capability_plan_missing: '为高影响 capability 节点补齐可用 Brief 与获取计划，或改为明确的其他路由',
+  capability_route_evidence: '为该节点补齐路由所需的 Intent 回链、Brief 或延后/排除理由，避免只写一个状态标签',
+  capability_outcome_unexpanded: '将 outcome 连接到至少一个 concern，明确项目初衷需要被处理的问题面',
+  capability_outcome_unobservable: '为高影响 outcome 新建或补齐 evidence 节点，并以 validated_by 连接；evidence 必须写明观察目标、复现步骤、通过标准、证据产物，并回链承担验证的 Intent',
+  intent_graph_unmapped: '将该 Intent 回链到至少一个 Capability Graph 节点；不要让执行承诺失去项目初衷和能力来源',
+  capability_proposal_pending: '由 Architect 审核 proposal：判定已覆盖、更新 Graph、生成/修订 Intent、改变 acceptance，或升级 Minor/Major；Forge 不得静默把候选写进正式图谱。',
+  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。',
+};
 
 /**
  * 给 issue 补 fix_hint——把 {id} {dep} 等占位符替换成实际值。
@@ -196,8 +216,76 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
     return { issues: issuesWithHints, summary: summarizeIssues(issuesWithHints) };
   }
 
-  const { intents } = mapState.validMap;
-
+  const { intents } = mapState.validMap;
+  const atelierRecords = new Map();
+
+  for (const [id, intent] of Object.entries(intents)) {
+    if (intent.quality_strategy !== 'atelier' || intent.status === 'pending' || intent.status === 'blocked') continue;
+    try {
+      const record = validateAtelierRecord(versionDir, id);
+      atelierRecords.set(id, record);
+      if (intent.status === 'completed' && !['selected', 'baseline_retained'].includes(record.status)) {
+        issues.push({ id, type: 'atelier_record_invalid', severity: 'high', msg: `${id} 已 completed，但 Atelier Record 仍是 ${record.status}` });
+      }
+    } catch (error) {
+      issues.push({ id, type: 'atelier_record_invalid', severity: 'high', msg: error.message });
+    }
+  }
+
+  // 0. Incoming Graph changes are an Architect gate, not Forge implementation scope.
+  try {
+    for (const proposal of listCapabilityProposals(versionDir, { unresolvedOnly: true })) {
+      issues.push({ id: proposal.id, type: 'capability_proposal_pending', severity: 'high', msg: `${proposal.id} 是尚未闭合的 ${proposal.origin} 候选（${proposal.candidate_kind}: ${proposal.title}）；必须由 Architect 决定其影响。` });
+    }
+  } catch (error) {
+    issues.push({ id: 'capability_proposals', type: 'capability_proposal_pending', severity: 'high', msg: `Capability Graph proposal 无法审计: ${error.message}` });
+  }
+
+  // Asset Library is optional for a project, but once initialized it is a local source of truth.
+  if (existsSync(getAssetManifestPath(versionDir))) {
+    try { validateAssetLibrary(versionDir); } catch (error) {
+      issues.push({ id: 'asset_library', type: 'asset_library_invalid', severity: 'high', msg: error.message });
+    }
+  }
+
+  // 0. Capability Graph：旧项目允许缺失但提示迁移；图谱一旦存在则必须可读、可路由。
+  const capabilityGraphPath = getCapabilityGraphPath(versionDir);
+  if (!existsSync(capabilityGraphPath)) {
+    issues.push({ id: 'capability_graph', type: 'capability_graph_missing', severity: 'medium', msg: '缺少 07_CAPABILITY_GRAPH.json；现有项目仍可运行，但不会获得图谱驱动的能力拆分与覆盖检查。' });
+  } else {
+    try {
+      const graph = loadCapabilityGraph(versionDir);
+      if (graph._meta?._template === true) {
+        issues.push({ id: 'capability_graph', type: 'capability_graph_template', severity: 'high', msg: 'Capability Graph 仍是模板；不得在未路由项目问题与能力缺口时宣告架构完成。' });
+      } else {
+        const coverage = getCapabilityCoverage(versionDir);
+        for (const node of coverage.high_unrouted) {
+          issues.push({ id: node.id, type: 'capability_frontier_open', severity: 'high', msg: `${node.id} 是尚未路由的高影响 Capability Graph 节点: ${node.title}` });
+        }
+        for (const item of coverage.capabilities_without_plan) {
+          issues.push({ id: item.node_id, type: 'capability_plan_missing', severity: 'high', msg: `${item.node_id} 的能力获取计划不完整: ${item.reason}` });
+        }
+        for (const item of coverage.routing_gaps) {
+          issues.push({ id: item.node_id, type: 'capability_route_evidence', severity: 'high', msg: `${item.node_id} 的图谱路由缺少依据: ${item.reason}` });
+        }
+        for (const item of coverage.outcomes_without_concern) {
+          issues.push({ id: item.node_id, type: 'capability_outcome_unexpanded', severity: 'high', msg: `${item.node_id} 没有展开为项目问题面: ${item.reason}` });
+        }
+        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.orphan_intent_refs) {
+          issues.push({ id: item.node_id, type: 'intent_graph_unmapped', severity: 'high', msg: `${item.node_id} 引用了不存在的 Intent: ${item.intent_id}` });
+        }
+        for (const intentId of coverage.unmapped_intents) {
+          issues.push({ id: intentId, type: 'intent_graph_unmapped', severity: 'high', msg: `${intentId} 没有 Capability Graph 回链；执行承诺缺少能力与问题来源。` });
+        }
+      }
+    } catch (error) {
+      issues.push({ id: 'capability_graph', type: 'capability_graph_invalid', severity: 'high', msg: error.message });
+    }
+  }
+
   // 1. 状态一致性：completed 必须由当前 revision 的最后一条 passed 验证支撑。
   for (const [id, intent] of Object.entries(intents)) {
     const history = getVerificationHistory(verificationsDir, id);
@@ -229,6 +317,47 @@ 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
+        || latest.atelier?.record_ref !== `09_ATELIER/${id}.json`
+        || latest.atelier?.stance_revision !== atelier.stance_revision
+        || latest.atelier?.status !== atelier.status) {
+        issues.push({
+          id,
+          type: 'atelier_verification_missing',
+          severity: 'high',
+          msg: `${id} 的最新 passed 未绑定当前 Atelier Record、status 与 stance_revision`,
+        });
+      }
+    }
     if (intent.continuity_required && latest?.verdict === 'passed') {
       const preservation = latest.dimensions?.preservation_achievement;
       if (!preservation || preservation.verdict !== 'passed') {

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');
+}