@haaaiawd/loom 1.2.1 → 1.3.1

package/cli/src/capability-graph.js

@@ -12,8 +12,22 @@ const NODE_STATUSES = ['open', 'researched', 'covered', 'deferred', 'out_of_scop
 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 FAILURE_COSTS = ['low', 'material', 'hard_to_reverse'];
+const IMPACT_REVIEWER_MODES = ['independent_agent_thread'];
 const VERIFICATION_FIELDS = ['method', 'target', 'procedure', 'pass_criteria', 'artifact'];
 const EVIDENCE_ARTIFACT_DIRS = ['verifications', '08_ASSET_LIBRARY/files'];
+const LENS_STATUSES = ['applicable', 'not_applicable'];
+// A lens is a mandatory inspection direction, not a capability category.  The
+// graph may decide that a lens does not apply, but it must make that decision
+// visible instead of silently omitting, for example, interaction quality.
+const STANDARD_LENSES = [
+  { id: 'journey', title: '用户旅程', question: '用户从开始到离开，是否能完成有意义的完整路径？' },
+  { id: 'interaction_accessibility', title: '交互与可访问性', question: '状态、反馈、失败恢复和不同使用条件是否真实可用？' },
+  { id: 'visual_editorial', title: '视觉与信息表达', question: '视觉语言、层级、版式与资产是否帮助用户理解并形成该产品的气质？' },
+  { id: 'content_communication', title: '内容与沟通', question: '文案、信息呈现或对话是否准确、可理解且符合产品立场？' },
+  { id: 'system_data', title: '系统与数据', question: '数据、模型、集成、权限与运行边界是否支撑而非伤害用户结果？' },
+  { id: 'quality_risk', title: '横切质量与风险', question: '可靠性、隐私、安全、性能、素材来源与独立验证是否被处理？' },
+];
 
 export function getCapabilityGraphPath(versionDir) {
   return join(versionDir, GRAPH_FILE);
@@ -27,7 +41,193 @@ function assertString(value, label, errors) {
   if (typeof value !== 'string' || value.trim() === '') errors.push(`${label} 必须是非空字符串`);
 }
 
-function validateNode(id, node, allIds, errors) {
+function schemaRequiresLensContract(data) {
+  const version = Number.parseFloat(String(data?._meta?._version || '1.0'));
+  return Number.isFinite(version) && version >= 1.1;
+}
+
+function schemaRequiresCapabilityDomains(data) {
+  const version = Number.parseFloat(String(data?._meta?._version || '1.0'));
+  return Number.isFinite(version) && version >= 1.2;
+}
+
+function schemaRequiresImpactAssessment(data) {
+  const version = Number.parseFloat(String(data?._meta?._version || '1.0'));
+  return Number.isFinite(version) && version >= 1.3;
+}
+
+function minimumHighCapabilityCount(totalCapabilities) {
+  return Math.max(1, Math.ceil(totalCapabilities * 0.3));
+}
+
+function validateImpactReview(data, capabilities, errors) {
+  if (data?._meta?._template === true) return;
+  const review = data.impact_review;
+  if (!review || typeof review !== 'object' || Array.isArray(review)) {
+    errors.push('Graph schema 1.3 要求 impact_review；Architect 提出判断后，必须由新的 Agent thread 独立审查每个 capability 的影响等级与外部获取必要性');
+    return;
+  }
+  if (!IMPACT_REVIEWER_MODES.includes(review.reviewer_mode)) {
+    errors.push(`impact_review.reviewer_mode 必须为 independent_agent_thread；不能由 Architect 在同一上下文替自己确认影响等级`);
+  }
+  if (!Array.isArray(review.assessments)) {
+    errors.push('impact_review.assessments 必须是数组');
+    return;
+  }
+  const assessmentByCapability = new Map();
+  for (const [index, assessment] of review.assessments.entries()) {
+    const prefix = `impact_review.assessments[${index}]`;
+    if (!assessment || typeof assessment !== 'object' || Array.isArray(assessment)) {
+      errors.push(`${prefix} 必须是对象`);
+      continue;
+    }
+    assertString(assessment.capability_id, `${prefix}.capability_id`, errors);
+    if (!['low', 'medium', 'high'].includes(assessment.recommended_impact)) {
+      errors.push(`${prefix}.recommended_impact 非法: ${assessment.recommended_impact}`);
+    }
+    if (typeof assessment.external_acquisition_required !== 'boolean') {
+      errors.push(`${prefix}.external_acquisition_required 必须是 boolean`);
+    }
+    assertString(assessment.rationale, `${prefix}.rationale`, errors);
+    if (assessmentByCapability.has(assessment.capability_id)) errors.push(`${prefix}.capability_id 重复: ${assessment.capability_id}`);
+    assessmentByCapability.set(assessment.capability_id, assessment);
+  }
+
+  const capabilityIds = new Set(capabilities.map((node) => node.id));
+  for (const capability of capabilities) {
+    const assessment = assessmentByCapability.get(capability.id);
+    if (!assessment) {
+      errors.push(`impact_review 缺少 ${capability.id} 的独立审查；不要让 Architect 自己裁决它是否重要`);
+      continue;
+    }
+    if (assessment.recommended_impact !== capability.impact) {
+      errors.push(`impact_review 对 ${capability.id} 建议 ${assessment.recommended_impact}，但 Graph 写为 ${capability.impact}；先按独立审查结论更新图谱或重新审查`);
+    }
+    const effectiveAcquisition = getEffectiveAcquisitionMode(capability);
+    if (assessment.external_acquisition_required && effectiveAcquisition !== 'external_required') {
+      errors.push(`impact_review 要求 ${capability.id} 外部获取，但 Graph 的 acquisition_mode 为 ${effectiveAcquisition}`);
+    }
+  }
+  for (const capabilityId of assessmentByCapability.keys()) {
+    if (!capabilityIds.has(capabilityId)) errors.push(`impact_review 引用不存在的 capability: ${capabilityId}`);
+  }
+  const highCount = capabilities.filter((node) => node.impact === 'high').length;
+  const requiredHighCount = minimumHighCapabilityCount(capabilities.length);
+  if (highCount < requiredHighCount) {
+    errors.push(`Impact Gate 要求至少 ${requiredHighCount}/${capabilities.length}（30%，向上取整，至少 1 个）capability 为 high；当前只有 ${highCount} 个。不要通过整体降级来跳过检索`);
+  }
+}
+
+function validateImpactAssessment(id, node, required, errors) {
+  const prefix = `nodes["${id}"].impact_assessment`;
+  const assessment = node.impact_assessment;
+  if (assessment === undefined) {
+    if (required) errors.push(`nodes["${id}"] 是 capability；Graph schema 1.3 要求 impact_assessment，先说明它影响的用户结果、错判代价、外部知识是否会改变决定与理由，再决定 impact`);
+    return;
+  }
+  if (!assessment || typeof assessment !== 'object' || Array.isArray(assessment)) {
+    errors.push(`${prefix} 必须是对象`);
+    return;
+  }
+  assertString(assessment.affected_user_result, `${prefix}.affected_user_result`, errors);
+  if (!FAILURE_COSTS.includes(assessment.failure_cost)) {
+    errors.push(`${prefix}.failure_cost 非法: ${assessment.failure_cost}（可选 low|material|hard_to_reverse）`);
+  }
+  if (typeof assessment.external_knowledge_changes_decision !== 'boolean') {
+    errors.push(`${prefix}.external_knowledge_changes_decision 必须是 boolean`);
+  }
+  assertString(assessment.rationale, `${prefix}.rationale`, errors);
+
+  const mustBeHigh = assessment.failure_cost === 'hard_to_reverse'
+    || assessment.external_knowledge_changes_decision === true;
+  if (mustBeHigh && node.impact !== 'high') {
+    errors.push(`nodes["${id}"] 的 impact_assessment 表明错判不可逆或外部知识会改变决定，impact 必须为 high；不能以 medium/low 绕过能力获取门禁`);
+  }
+  if (node.impact === 'high' && assessment.external_knowledge_changes_decision !== true) {
+    errors.push(`nodes["${id}"] 为 high capability，impact_assessment.external_knowledge_changes_decision 必须为 true；高影响能力必须进入外部获取判断`);
+  }
+}
+
+function validateCapabilityDomains(data, allIds, errors) {
+  if (data?._meta?._template === true) return new Set();
+  const domains = data.capability_domains;
+  if (domains === undefined) return new Set();
+  if (!Array.isArray(domains)) {
+    errors.push('capability_domains 必须是数组');
+    return new Set();
+  }
+  const seen = new Set();
+  for (const [index, domain] of domains.entries()) {
+    const prefix = `capability_domains[${index}]`;
+    if (!domain || typeof domain !== 'object' || Array.isArray(domain)) {
+      errors.push(`${prefix} 必须是对象`);
+      continue;
+    }
+    assertString(domain.id, `${prefix}.id`, errors);
+    assertString(domain.title, `${prefix}.title`, errors);
+    assertString(domain.question, `${prefix}.question`, errors);
+    assertString(domain.why_now, `${prefix}.why_now`, errors);
+    if (seen.has(domain.id)) errors.push(`${prefix}.id 重复: ${domain.id}`);
+    seen.add(domain.id);
+    if (!Array.isArray(domain.node_refs) || domain.node_refs.length === 0) {
+      errors.push(`${prefix}.node_refs 必须连接至少一个具体 capability 节点`);
+    } else {
+      for (const nodeId of domain.node_refs) {
+        if (!allIds.has(nodeId)) errors.push(`${prefix}.node_refs 指向不存在节点: ${nodeId}`);
+        else if (data.nodes[nodeId]?.kind !== 'capability') errors.push(`${prefix}.node_refs 只能引用 capability 节点: ${nodeId}`);
+      }
+    }
+  }
+  return seen;
+}
+
+function validateLensContract(data, allIds, errors) {
+  if (data?._meta?._template === true) return;
+  const contract = data.lens_contract;
+  if (contract === undefined) return;
+  if (!contract || typeof contract !== 'object' || Array.isArray(contract)) {
+    errors.push('lens_contract 必须是对象');
+    return;
+  }
+  assertString(contract.selection_basis, 'lens_contract.selection_basis', errors);
+  if (!Array.isArray(contract.lenses)) {
+    errors.push('lens_contract.lenses 必须是数组');
+    return;
+  }
+  const seen = new Set();
+  for (const [index, lens] of contract.lenses.entries()) {
+    const prefix = `lens_contract.lenses[${index}]`;
+    if (!lens || typeof lens !== 'object' || Array.isArray(lens)) {
+      errors.push(`${prefix} 必须是对象`);
+      continue;
+    }
+    assertString(lens.id, `${prefix}.id`, errors);
+    assertString(lens.title, `${prefix}.title`, errors);
+    assertString(lens.question, `${prefix}.question`, errors);
+    if (!LENS_STATUSES.includes(lens.status)) errors.push(`${prefix}.status 非法: ${lens.status}`);
+    if (seen.has(lens.id)) errors.push(`${prefix}.id 重复: ${lens.id}`);
+    seen.add(lens.id);
+    if (lens.status === 'applicable') {
+      if (!Array.isArray(lens.node_refs) || lens.node_refs.length === 0) {
+        errors.push(`${prefix}.status=applicable 必须用 node_refs 连接至少一个具体 Graph 节点`);
+      } else {
+        for (const nodeId of lens.node_refs) {
+          if (!allIds.has(nodeId)) errors.push(`${prefix}.node_refs 指向不存在节点: ${nodeId}`);
+        }
+      }
+    }
+    if (lens.status === 'not_applicable') {
+      assertString(lens.rationale, `${prefix}.rationale`, errors);
+    }
+  }
+  if (schemaRequiresLensContract(data)) {
+    for (const lens of STANDARD_LENSES) {
+      if (!seen.has(lens.id)) errors.push(`lens_contract 缺少必审透镜: ${lens.id}（${lens.title}）`);
+    }
+  }
+}
+
+function validateNode(id, node, allIds, domainIds, requireCapabilityDomains, requireImpactAssessment, errors) {
   if (!node || typeof node !== 'object' || Array.isArray(node)) {
     errors.push(`nodes["${id}"] 必须是对象`);
     return;
@@ -67,6 +267,22 @@ function validateNode(id, node, allIds, errors) {
   if (node.asset_refs !== undefined && node.kind !== 'evidence') {
     errors.push(`nodes["${id}"].asset_refs 只允许写在 evidence 节点`);
   }
+  if (node.domain_refs !== undefined && (!Array.isArray(node.domain_refs) || node.domain_refs.some((ref) => typeof ref !== 'string' || !ref.trim()))) {
+    errors.push(`nodes["${id}"].domain_refs 必须是非空字符串数组`);
+  } else if (node.domain_refs !== undefined) {
+    for (const domainId of node.domain_refs) {
+      if (!domainIds.has(domainId)) errors.push(`nodes["${id}"].domain_refs 指向不存在能力领域: ${domainId}`);
+    }
+  }
+  if (requireCapabilityDomains && node.kind === 'capability'
+    && (!Array.isArray(node.domain_refs) || node.domain_refs.length === 0)) {
+    errors.push(`nodes["${id}"] 是 capability，必须用 domain_refs 回链至少一个 capability domain`);
+  }
+  if (node.kind === 'capability') {
+    validateImpactAssessment(id, node, requireImpactAssessment, errors);
+  } else if (node.impact_assessment !== undefined) {
+    errors.push(`nodes["${id}"].impact_assessment 只允许写在 capability 节点`);
+  }
   if (node.acquisition_mode !== undefined) {
     if (node.kind !== 'capability') {
       errors.push(`nodes["${id}"].acquisition_mode 只允许写在 capability 节点`);
@@ -78,7 +294,10 @@ function validateNode(id, node, allIds, errors) {
     && (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'
+  if (node.impact === 'high' && requireImpactAssessment
+    && node.acquisition_mode !== undefined && node.acquisition_mode !== 'external_required') {
+    errors.push(`nodes["${id}"] 为 high capability；Graph schema 1.3 只允许 acquisition_mode=external_required（或省略并使用默认值），不得以 ${node.acquisition_mode} 绕过外部获取门禁`);
+  } else 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`);
   }
@@ -104,7 +323,16 @@ export function validateCapabilityGraph(data) {
     errors.push('缺少 nodes 对象');
   } else {
     const ids = new Set(Object.keys(data.nodes));
-    for (const [id, node] of Object.entries(data.nodes)) validateNode(id, node, ids, errors);
+    const domainIds = validateCapabilityDomains(data, ids, errors);
+    const requireCapabilityDomains = schemaRequiresCapabilityDomains(data) && data.capability_domains !== undefined;
+    const requireImpactAssessment = schemaRequiresImpactAssessment(data);
+    validateLensContract(data, ids, errors);
+    for (const [id, node] of Object.entries(data.nodes)) {
+      validateNode(id, node, ids, domainIds, requireCapabilityDomains, requireImpactAssessment, errors);
+    }
+    if (requireImpactAssessment) {
+      validateImpactReview(data, Object.values(data.nodes).filter((node) => node?.kind === 'capability'), errors);
+    }
     for (const [id, node] of Object.entries(data.nodes)) {
       if (node?.route !== 'covered_by') continue;
       const targetId = node.covered_by;
@@ -204,11 +432,31 @@ export function getCapabilityGraphProjection(versionDir) {
       total: Object.keys(graph.nodes).length,
       by_kind: Object.fromEntries(NODE_KINDS.map((kind) => [kind, Object.values(graph.nodes).filter((node) => node.kind === kind).length])),
       frontier: getCapabilityFrontier(versionDir).length,
+      lenses: getLensSummary(graph),
+      capability_domains: getDomainSummary(graph),
     },
     mermaid: lines.join('\n'),
   };
 }
 
+function getLensSummary(graph) {
+  const lenses = graph.lens_contract?.lenses || [];
+  return {
+    required: schemaRequiresLensContract(graph),
+    declared: lenses.length,
+    applicable: lenses.filter((lens) => lens.status === 'applicable').length,
+    not_applicable: lenses.filter((lens) => lens.status === 'not_applicable').length,
+  };
+}
+
+function getDomainSummary(graph) {
+  const domains = graph.capability_domains || [];
+  return {
+    required: schemaRequiresCapabilityDomains(graph),
+    declared: domains.length,
+  };
+}
+
 function resolveBrief(versionDir, briefRef) {
   if (!briefRef) return null;
   if (isAbsolute(briefRef)) throw new Error(`Capability Brief 不得使用绝对路径: ${briefRef}`);
@@ -238,7 +486,7 @@ function resolveEvidenceArtifact(versionDir, artifactRef) {
   return artifactPath;
 }
 
-function getHighOutcomesWithoutObservableEvidence(versionDir, graph, intentMap, intentMappingRequired) {
+function getHighOutcomesWithoutObservableEvidence(graph, intentMap, intentMappingRequired) {
   const gaps = [];
   for (const outcome of Object.values(graph.nodes)) {
     if (outcome.kind !== 'outcome' || outcome.impact !== 'high') continue;
@@ -246,7 +494,6 @@ function getHighOutcomesWithoutObservableEvidence(versionDir, graph, intentMap,
     const validEvidence = evidenceRelations.find((relation) => {
       const evidence = graph.nodes[relation.target];
       if (!evidence || evidence.kind !== 'evidence' || !evidence.verification) return false;
-      if (!resolveEvidenceArtifact(versionDir, evidence.verification.artifact)) return false;
       const hasOwner = (evidence.intent_refs || []).some((intentId) => !intentMappingRequired || intentId in intentMap.intents);
       return hasOwner;
     });
@@ -265,6 +512,8 @@ export function getCapabilityCoverage(versionDir) {
   const intentMap = loadIntentMap(versionDir);
   const intentMappingRequired = intentMap._meta?._template !== true;
   const nodes = Object.values(graph.nodes);
+  const capabilityNodes = nodes.filter((node) => node.kind === 'capability');
+  const highCapabilityCount = capabilityNodes.filter((node) => node.impact === 'high').length;
   const highUnrouted = getCapabilityFrontier(versionDir);
   const orphanIntentRefs = [];
   const mappedIntentIds = new Set();
@@ -272,6 +521,19 @@ export function getCapabilityCoverage(versionDir) {
   const routingGaps = [];
   const outcomesWithoutConcern = [];
   const evidenceArtifactGaps = [];
+  const lensContractGaps = [];
+  const capabilityDomainGaps = [];
+
+  if (schemaRequiresLensContract(graph) && !graph.lens_contract) {
+    lensContractGaps.push({
+      reason: '当前 Graph schema 要求 lens_contract；Architect 必须先审视用户旅程、交互与可访问性、视觉与信息表达、内容与沟通、系统与数据、横切质量与风险，并把每项连接到具体节点或说明为何不适用。',
+    });
+  }
+  if (schemaRequiresCapabilityDomains(graph) && !graph.capability_domains) {
+    capabilityDomainGaps.push({
+      reason: '当前 Graph schema 要求 capability_domains；Architect 必须从项目事实派生会改变方案或验证方法的专业领域（如 UI/UX、3D 与光影、网络安全、心理学或生物学），再把具体 capability 回链到这些领域。',
+    });
+  }
 
   for (const node of nodes) {
     for (const intentId of node.intent_refs || []) {
@@ -326,11 +588,15 @@ export function getCapabilityCoverage(versionDir) {
   const unmappedIntents = intentMappingRequired
     ? Object.keys(intentMap.intents).filter((id) => !mappedIntentIds.has(id))
     : [];
-  const highOutcomesWithoutObservableEvidence = getHighOutcomesWithoutObservableEvidence(versionDir, graph, intentMap, intentMappingRequired);
+  const highOutcomesWithoutObservableEvidence = getHighOutcomesWithoutObservableEvidence(graph, intentMap, intentMappingRequired);
   return {
     summary: {
       nodes: nodes.length,
       outcomes: nodes.filter((node) => node.kind === 'outcome').length,
+      capabilities: capabilityNodes.length,
+      high_capabilities: highCapabilityCount,
+      required_high_capabilities: capabilityNodes.length ? minimumHighCapabilityCount(capabilityNodes.length) : 0,
+      high_capability_ratio: capabilityNodes.length ? highCapabilityCount / capabilityNodes.length : 0,
       high_unrouted: highUnrouted.length,
       orphan_intent_refs: orphanIntentRefs.length,
       capabilities_without_plan: capabilitiesWithoutPlan.length,
@@ -338,6 +604,10 @@ export function getCapabilityCoverage(versionDir) {
       outcomes_without_concern: outcomesWithoutConcern.length,
       high_outcomes_without_observable_evidence: highOutcomesWithoutObservableEvidence.length,
       evidence_artifact_gaps: evidenceArtifactGaps.length,
+      lens_contract_gaps: lensContractGaps.length,
+      capability_domain_gaps: capabilityDomainGaps.length,
+      lenses: getLensSummary(graph),
+      capability_domains: getDomainSummary(graph),
       intent_mapping_required: intentMappingRequired,
       unmapped_intents: unmappedIntents.length,
       ready: highUnrouted.length === 0
@@ -347,6 +617,8 @@ export function getCapabilityCoverage(versionDir) {
         && outcomesWithoutConcern.length === 0
         && highOutcomesWithoutObservableEvidence.length === 0
         && evidenceArtifactGaps.length === 0
+        && lensContractGaps.length === 0
+        && capabilityDomainGaps.length === 0
         && unmappedIntents.length === 0,
     },
     high_unrouted: highUnrouted,
@@ -356,6 +628,8 @@ export function getCapabilityCoverage(versionDir) {
     outcomes_without_concern: outcomesWithoutConcern,
     high_outcomes_without_observable_evidence: highOutcomesWithoutObservableEvidence,
     evidence_artifact_gaps: evidenceArtifactGaps,
+    lens_contract_gaps: lensContractGaps,
+    capability_domain_gaps: capabilityDomainGaps,
     unmapped_intents: unmappedIntents,
   };
 }
@@ -395,6 +669,24 @@ export function compileCapabilityInputs(versionDir, intentId) {
     };
   }
   const nodes = collectCompilationNodes(graph, intentId);
+  const relevantLenses = (graph.lens_contract?.lenses || [])
+    .filter((lens) => lens.status === 'applicable'
+      && (lens.node_refs || []).some((nodeId) => nodes.some((node) => node.id === nodeId)))
+    .map((lens) => ({
+      id: lens.id,
+      title: lens.title,
+      question: lens.question,
+      node_refs: lens.node_refs,
+    }));
+  const relevantDomains = (graph.capability_domains || [])
+    .filter((domain) => (domain.node_refs || []).some((nodeId) => nodes.some((node) => node.id === nodeId)))
+    .map((domain) => ({
+      id: domain.id,
+      title: domain.title,
+      question: domain.question,
+      why_now: domain.why_now,
+      node_refs: domain.node_refs,
+    }));
   const briefs = [];
   const warnings = [];
   for (const node of nodes) {
@@ -419,6 +711,8 @@ export function compileCapabilityInputs(versionDir, intentId) {
   return {
     available: true,
     nodes,
+    lenses: relevantLenses,
+    capability_domains: relevantDomains,
     briefs,
     warnings,
     acquisition: {

package/cli/src/diagnostics.js

@@ -16,6 +16,7 @@ import { listCapabilityProposals } from './capability-proposals.js';
 import { getAssetManifestPath, validateAssetLibrary } from './asset-library.js';
 import { validateAtelierRecord } from './atelier.js';
 import { getExpertisePackState } from './expertise-pack.js';
+import { validateAtlas } from './atlas.js';
 
 function readIntentMapRaw(versionDir) {
   const filePath = join(versionDir, '04_INTENT_MAP.json');
@@ -146,12 +147,18 @@ function commandCoversMethod(actualCommand, expectedMethod) {
 const FIX_HINTS = {
   intent_map_unreadable: '检查 .loom/v{N}/04_INTENT_MAP.json 是否合法 JSON（jsonlint.com 或 node -e "JSON.parse(require(\'fs\').readFileSync(\'04_INTENT_MAP.json\'))"）',
   intent_map_missing: '运行 loom init 或 loom activate architect 产出 04_INTENT_MAP.json',
-  intent_map_template: '运行 loom activate architect，Architect 填充真实 Intent Map 后删除 _meta._template 标记',
-  intent_map_invalid: '按报错信息修正 04_INTENT_MAP.json 里对应字段（补 title / 加长 acceptance / 填必填字段）',
+  intent_map_template: '运行 loom activate architect，Architect 填充真实 Intent Map 后删除 _meta._template 标记',
+  intent_map_invalid: '按报错信息修正 04_INTENT_MAP.json 里对应字段（补 title / 加长 acceptance / 填必填字段）',
+  project_document_missing: '运行 loom activate architect，补齐当前版本缺失的项目文档；不要靠 Intent Map 或会话记忆替代 Vision、Architecture、Verification 的可审计载体',
+  project_document_template: '运行 loom activate architect，将仍带 LOOM_TEMPLATE 标记的项目文档替换为本项目的真实判断与契约后删除标记',
+  intent_narrative_invalid: '修正 {id}.narrative_ref 到 01_VISION.md 中实际存在的章节；可运行 loom intent narrative {id} 复核',
+  intent_contract_invalid: '修正 {id}.acceptance 或其对 05_VERIFICATION.md 的章节引用；可运行 loom verify contract {id} 复核',
   completed_no_record: '在 .loom/v{N}/verifications/ 下补验证记录，或运行 loom verify pass {id} --summary "..."',
   completed_verification_not_passed: '最新验证不是当前 revision 的 passed；重新运行 loom verify pass {id} --summary "..."，再用 loom intent done {id} 闭合。',
   in_progress_no_record: '运行 loom verify pass {id} --summary "..." 写入验证记录，或 loom intent update {id} --status pending 回退',
-  orphan_philosophy_ref: '检查 04_INTENT_MAP.json 里 {id} 的 philosophy_anchors，移除或修正不存在的哲学文件引用',
+  orphan_philosophy_ref: '检查 04_INTENT_MAP.json 里 {id} 的 philosophy_anchors，移除或修正不存在的哲学文件引用',
+  orphan_philosophy_anchor: '修正 {id} 的 philosophy_anchors 中 # 后的章节锚点；可运行 loom philosophy get <file#anchor> 检查该章节是否可读取',
+  orphan_philosophy_anchor: '修正 {id} 的 philosophy_anchors 中 # 后的章节锚点；可运行 loom philosophy get <file#anchor> 检查该章节是否可读取',
   orphan_dependency: '检查 04_INTENT_MAP.json 里 {id} 的 depends_on，移除或修正不存在的 Intent ID',
   cycle: '打破循环：把循环链中某个 Intent 的 depends_on 里去掉前驱，或拆成更小的 Intent',
   zombie: '检查 {id} 是否还需要——不需要就 loom intent update {id} --status completed 或 blocked',
@@ -174,6 +181,10 @@ const FIX_HINTS = {
   capability_route_evidence: '为该节点补齐路由所需的 Intent 回链、Brief 或延后/排除理由，避免只写一个状态标签',
   capability_outcome_unexpanded: '将 outcome 连接到至少一个 concern，明确项目初衷需要被处理的问题面',
   capability_outcome_unobservable: '为高影响 outcome 新建或补齐 evidence 节点，并以 validated_by 连接；evidence 必须写明观察目标、复现步骤、通过标准、证据产物，并回链承担验证的 Intent',
+  capability_lens_contract_missing: '运行 loom activate architect；按用户旅程、交互与可访问性、视觉与信息表达、内容与沟通、系统与数据、横切质量与风险审视本项目。每项都要连接具体节点，或写明为何不适用；不要把“UI/UX”当成空泛节点。',
+  capability_domain_contract_missing: '运行 loom activate architect；从项目事实派生会改变方案或验证方法的专业领域（例如 UI/UX、3D 与光影、网络安全、心理学、生物学），并让每个具体 capability 用 domain_refs 回链。领域不是部门标签，必须说明它改变什么决定。',
+  capability_impact_gate_missing: '运行 loom activate architect；先为每个 capability 写 impact_assessment：影响的用户结果、错判代价、外部知识是否会改变决定及理由。不可逆或会受外部知识影响的能力必须标为 high，并进入 external_required。',
+  decision_atlas_missing: '当前版本的 Intent 已全部闭合，但缺少合格的 loom-atlas.html；运行 loom atlas --regen，用已装配的 Composer Pack 生成后再运行 loom atlas validate。',
   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。',
@@ -186,7 +197,7 @@ const FIX_HINTS = {
 /**
  * 给 issue 补 fix_hint——把 {id} {dep} 等占位符替换成实际值。
  */
-function addFixHint(issue) {
+function addFixHint(issue) {
   const template = FIX_HINTS[issue.type];
   if (!template) return issue;
   let hint = template;
@@ -218,6 +229,22 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
 
   const { intents } = mapState.validMap;
   const atelierRecords = new Map();
+  appendProjectDocumentStructureDiagnostics(issues, versionDir, philosophyDir);
+
+  // Atlas is a completion deliverable, not a live dashboard. It becomes a
+  // hard gate only after all designed Intents are completed.
+  const allIntents = Object.values(intents);
+  if (allIntents.length > 0 && allIntents.every((intent) => intent.status === 'completed')) {
+    const atlas = validateAtlas(join(versionDir, '..', '..'), versionDir);
+    if (!atlas.valid) {
+      issues.push({
+        id: 'decision_atlas',
+        type: 'decision_atlas_missing',
+        severity: 'high',
+        msg: `当前版本所有 Intent 已完成，但决策图谱尚未成为合格交付物: ${atlas.errors.join('；')}`,
+      });
+    }
+  }
 
   for (const [id, intent] of Object.entries(intents)) {
     if (intent.quality_strategy !== 'atelier' || intent.status === 'pending' || intent.status === 'blocked') continue;
@@ -277,6 +304,12 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
         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.lens_contract_gaps || []) {
+          issues.push({ id: 'capability_graph', type: 'capability_lens_contract_missing', severity: 'high', msg: `Capability Graph 尚未完成透镜审视: ${item.reason}` });
+        }
+        for (const item of coverage.capability_domain_gaps || []) {
+          issues.push({ id: 'capability_graph', type: 'capability_domain_contract_missing', severity: 'high', msg: `Capability Graph 尚未声明能力领域: ${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}` });
         }
@@ -285,7 +318,13 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
         }
       }
     } catch (error) {
-      issues.push({ id: 'capability_graph', type: 'capability_graph_invalid', severity: 'high', msg: error.message });
+      const impactGateError = /impact_assessment|impact_review|Impact Gate|impact 必须为 high|外部获取门禁|30%/.test(error.message);
+      issues.push({
+        id: 'capability_graph',
+        type: impactGateError ? 'capability_impact_gate_missing' : 'capability_graph_invalid',
+        severity: 'high',
+        msg: error.message,
+      });
     }
   }
 
@@ -374,19 +413,39 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
     }
   }
 
-  // 2. 孤儿引用：哲学锚点指向不存在的文件
-  for (const [id, intent] of Object.entries(intents)) {
-    if (!intent.philosophy_anchors) continue;
+  // 2. 孤儿引用：哲学锚点必须同时指向存在的文件和可读取的章节。
+  for (const [id, intent] of Object.entries(intents)) {
+    if (!intent.philosophy_anchors) continue;
     for (const anchor of intent.philosophy_anchors) {
       const [file] = anchor.split('#');
       const filePath = join(philosophyDir, file);
-      if (!existsSync(filePath)) {
-        issues.push({ id, type: 'orphan_philosophy_ref', severity: 'high', msg: `${id} 引用不存在的哲学文件: ${file}` });
-      }
-    }
-  }
-
-  // 3. 孤儿引用：depends_on 指向不存在的 Intent
+      if (!existsSync(filePath)) {
+        issues.push({ id, type: 'orphan_philosophy_ref', severity: 'high', msg: `${id} 引用不存在的哲学文件: ${file}` });
+      } else if (anchor.includes('#')) {
+        try {
+          getPhilosophy(philosophyDir, anchor);
+        } catch (error) {
+          issues.push({ id, type: 'orphan_philosophy_anchor', severity: 'high', msg: `${id} 引用不存在或不可读取的哲学章节: ${anchor}（${error.message}）` });
+        }
+      }
+    }
+  }
+
+  // Intent 的叙事与完成契约不能只是字符串；它们必须能从当前版本真实解析。
+  for (const [id] of Object.entries(intents)) {
+    try {
+      getNarrative(versionDir, id);
+    } catch (error) {
+      issues.push({ id, type: 'intent_narrative_invalid', severity: 'high', msg: `${id} 的 narrative_ref 无法解析: ${error.message}` });
+    }
+    try {
+      getVerificationContract(versionDir, id);
+    } catch (error) {
+      issues.push({ id, type: 'intent_contract_invalid', severity: 'high', msg: `${id} 的 acceptance 无法解析: ${error.message}` });
+    }
+  }
+
+  // 3. 孤儿引用：depends_on 指向不存在的 Intent
   for (const [id, intent] of Object.entries(intents)) {
     if (!intent.depends_on) continue;
     for (const dep of intent.depends_on) {
@@ -724,6 +783,40 @@ export function traceIntent(versionDir, verificationsDir, philosophyDir, intentI
     lineage: { predecessors, successors },
   };
 }
+
+const REQUIRED_PROJECT_DOCUMENTS = [
+  { relativePath: '01_VISION.md', label: 'Vision' },
+  { relativePath: '02_ARCHITECTURE.md', label: 'Architecture' },
+  { relativePath: '05_VERIFICATION.md', label: 'Verification' },
+];
+const REQUIRED_PHILOSOPHY_DOCUMENTS = [
+  'PRODUCT_PHILOSOPHY.md',
+  'ENGINEERING_CREED.md',
+  'DECISION_RUBRIC.md',
+];
+
+function isLoomTemplateDocument(filePath) {
+  return existsSync(filePath) && readFileSync(filePath, 'utf-8').includes('<!-- LOOM_TEMPLATE -->');
+}
+
+function appendProjectDocumentStructureDiagnostics(issues, versionDir, philosophyDir) {
+  for (const document of REQUIRED_PROJECT_DOCUMENTS) {
+    const filePath = join(versionDir, document.relativePath);
+    if (!existsSync(filePath)) {
+      issues.push({ id: document.relativePath, type: 'project_document_missing', severity: 'high', msg: `缺少 LOOM 必需项目文档: ${document.relativePath}（${document.label}）` });
+    } else if (isLoomTemplateDocument(filePath)) {
+      issues.push({ id: document.relativePath, type: 'project_document_template', severity: 'high', msg: `${document.relativePath} 仍是 LOOM_TEMPLATE，尚未成为当前项目的 ${document.label} 文档` });
+    }
+  }
+  for (const filename of REQUIRED_PHILOSOPHY_DOCUMENTS) {
+    const filePath = join(philosophyDir, filename);
+    if (!existsSync(filePath)) {
+      issues.push({ id: filename, type: 'project_document_missing', severity: 'high', msg: `缺少 LOOM 必需哲学文档: 00_PHILOSOPHY/${filename}` });
+    } else if (isLoomTemplateDocument(filePath)) {
+      issues.push({ id: filename, type: 'project_document_template', severity: 'high', msg: `00_PHILOSOPHY/${filename} 仍是 LOOM_TEMPLATE，尚未成为当前项目的哲学判断` });
+    }
+  }
+}
 
 // ─── reverse-dep ───────────────────────────────────────
 // 反向依赖：哪些 Intent 依赖这个 Intent