@haaaiawd/loom 0.10.0 → 1.1.0

package/cli/src/diagnostics.js

@@ -3,10 +3,18 @@
 // 全部是只读的数据聚合，不做决策、不修改文件。
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { loadIntentMap, getStatus, getNextIntent, getNarrative, getIntent } from './intent-map.js';
-import { getPhilosophy, validateInspirationSources, validatePartDecomposition } from './philosophy.js';
-import { getVerificationHistory, getPendingVerifications, getVerificationContract } from './verify.js';
+import { getPhilosophy, validateInspirationSources } from './philosophy.js';
+import { getVerificationHistory, getPendingVerifications, getVerificationContract, getLatestPassedVerification, getVerificationIntentRevision, isVerificationCurrent, hasCurrentPassedVerification } from './verify.js';
+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';
 
 function readIntentMapRaw(versionDir) {
   const filePath = join(versionDir, '04_INTENT_MAP.json');
@@ -75,10 +83,6 @@ function intentMapDiagnostics(versionDir) {
   return { raw, valid, issues, validMap };
 }
 
-function getIntentVerificationMethod(intent) {
-  return intent.verification_method || intent._optional?.verification_method || null;
-}
-
 function normalizeVerificationCommand(command) {
   return String(command || '')
     .replace(/^\s*run\s+/i, '')
@@ -143,7 +147,8 @@ const FIX_HINTS = {
   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 / 填必填字段）',
-  completed_no_record: '在 .loom/v{N}/verifications/ 下补验证记录，或运行 loom verify pass {id} --summary "..."',
+  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_dependency: '检查 04_INTENT_MAP.json 里 {id} 的 depends_on，移除或修正不存在的 Intent ID',
@@ -152,10 +157,28 @@ const FIX_HINTS = {
   completed_depends_blocked: '检查依赖 {dep} 为什么 blocked——解决阻塞或把 {id} 回退到 in_progress',
   test_script_missing: '在 package.json 里加 test 脚本，或修正 verification_method 指向实际存在的测试命令',
   verification_method_unverified: '运行 loom verify pass {id} --summary "..." --reproduction-command "..." 覆盖声明的验证方式',
-  verification_method_drift: '验证记录的 reproduction_command 要覆盖 verification_method 声明的命令（支持 npm/pnpm/bun 互相等价）',
-  inspiration_source: '在哲学文档的"灵感来源"章节填入至少 3 个源（- **源名** — 理由。来源：URL 或 file:// 或 local:./path）',
-  part_decomposition: '在哲学文档加"实现部分清单"章节，按 PART_DECOMPOSITION.md 拆解实现部分（- **部分名** 格式）',
-};
+  verification_method_drift: '验证记录的 reproduction_command 要覆盖 verification_method 声明的命令（支持 npm/pnpm/bun 互相等价）',
+  stale_verification: '重新验证当前 Intent revision：loom verify pass {id} --summary "..."，通过后再闭合 Intent',
+  inspiration_source: '在哲学文档的"证据地图/灵感来源"中写入实际使用的来源、选择理由和可追溯位置；数量由判断所需决定',
+  quality_dimension_missing: '为带 quality_contract 的 Intent 补写并通过 quality_achievement；相对提升声明在该维度中链接 Quality Proof',
+  quality_proof_invalid: '将 quality_proof_ref 改为项目内真实存在且含锚点的 Markdown 证据，例如 verifications/INT-001-quality-proof.md#int-001',
+  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。',
+};
 
 /**
  * 给 issue 补 fix_hint——把 {id} {dep} 等占位符替换成实际值。
@@ -190,18 +213,133 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
     return { issues: issuesWithHints, summary: summarizeIssues(issuesWithHints) };
   }
 
-  const { intents } = mapState.validMap;
-
-  // 1. 状态一致性：in_progress/completed 但无验证记录
-  for (const [id, intent] of Object.entries(intents)) {
-    const hasRecord = existsSync(join(verificationsDir, `${id}.json`));
-    if (intent.status === 'completed' && !hasRecord) {
-      issues.push({ id, type: 'completed_no_record', severity: 'high', msg: `${id} 状态为 completed 但无验证记录` });
-    }
-    if (intent.status === 'in_progress' && !hasRecord) {
-      issues.push({ id, type: 'in_progress_no_record', severity: 'medium', msg: `${id} 状态为 in_progress 但无验证记录（可能上次中断）` });
-    }
-  }
+  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);
+    const hasRecord = Boolean(history?.records?.length);
+    const latest = history?.records?.[history.records.length - 1];
+    if (intent.status === 'completed' && !hasRecord) {
+      issues.push({ id, type: 'completed_no_record', severity: 'high', msg: `${id} 状态为 completed 但无验证记录` });
+    } else if (intent.status === 'completed' && !hasCurrentPassedVerification(intent, history)) {
+      issues.push({ id, type: 'completed_verification_not_passed', severity: 'high', msg: `${id} 状态为 completed，但最后一条验证不是当前 revision 的 passed` });
+    }
+    if (intent.status === 'in_progress' && !hasRecord) {
+      issues.push({ id, type: 'in_progress_no_record', severity: 'medium', msg: `${id} 状态为 in_progress 但无验证记录（可能上次中断）` });
+    }
+    if (intent.quality_contract && latest?.verdict === 'passed') {
+      const quality = latest.dimensions?.quality_achievement;
+      if (!quality || quality.verdict !== 'passed') {
+        issues.push({
+          id,
+          type: 'quality_dimension_missing',
+          severity: 'high',
+          msg: `${id} 声明了 quality_contract，但最新 passed 记录缺少通过的 quality_achievement`,
+        });
+      }
+      if (quality?.quality_proof_ref) {
+        try {
+          resolveQualityProofReference(versionDir, quality.quality_proof_ref);
+        } catch (error) {
+          issues.push({ id, type: 'quality_proof_invalid', severity: 'high', msg: `${id} 的 Quality Proof 无效: ${error.message}` });
+        }
+      }
+    }
+    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') {
+        issues.push({
+          id,
+          type: 'preservation_dimension_missing',
+          severity: 'high',
+          msg: `${id} 声明了 continuity_required，但最新 passed 记录缺少通过的 preservation_achievement`,
+        });
+      }
+    }
+  }
 
   // 2. 孤儿引用：哲学锚点指向不存在的文件
   for (const [id, intent] of Object.entries(intents)) {
@@ -312,12 +450,42 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
       issues.push({ id, type: 'verification_method_unverified', severity: 'high', msg: `${id} 声明了 verification_method 但没有验证记录覆盖: ${method}` });
     } else if (!actual) {
       issues.push({ id, type: 'verification_method_unverified', severity: 'high', msg: `${id} 最新验证记录缺少 reproduction_command，无法复现 verification_method: ${method}` });
-    } else if (!commandCoversMethod(actual, expected)) {
+    } else if (!commandCoversVerificationMethod(actual, expected)) {
       issues.push({ id, type: 'verification_method_drift', severity: 'high', msg: `${id} verification_method 未被最新 reproduction_command 覆盖。method="${method}" reproduction_command="${latest.reproduction_command}"` });
     }
   }
 
-  appendPhilosophyDiagnostics(issues, philosophyDir);
+  const patchJsonPath = join(versionDir, '06_CHANGELOG.json');
+  if (existsSync(patchJsonPath)) {
+    try {
+      validatePatches(versionDir);
+    } catch (error) {
+      const projectionDrift = String(error.message).includes('最新确定性投影') || String(error.message).includes('Markdown 投影不存在');
+      issues.push({
+        id: 'patch_changelog',
+        type: projectionDrift ? 'patch_projection_drift' : 'patch_changelog_invalid',
+        severity: projectionDrift ? 'medium' : 'high',
+        msg: error.message,
+      });
+    }
+  }
+
+  // completed/needs_review 的旧 revision 验证不能证明当前 Intent 仍然成立。
+  for (const [id, intent] of Object.entries(intents)) {
+    if (intent.status !== 'completed' && intent.status !== 'needs_review') continue;
+    const history = getVerificationHistory(verificationsDir, id);
+    const latestPassed = getLatestPassedVerification(history);
+    if (!latestPassed || isVerificationCurrent(intent, latestPassed)) continue;
+    const verifiedRevision = getVerificationIntentRevision(intent, latestPassed);
+    issues.push({
+      id,
+      type: 'stale_verification',
+      severity: 'high',
+      msg: `${id} 最新 passed 验证 revision ${verifiedRevision ?? 'legacy/unknown'} 早于当前 Intent revision ${intent.revision ?? 1}`,
+    });
+  }
+
+  appendPhilosophyDiagnostics(issues, philosophyDir);
   const issuesWithHints = issues.map(addFixHint);
   return { issues: issuesWithHints, summary: summarizeIssues(issuesWithHints) };
 }
@@ -331,11 +499,6 @@ function appendPhilosophyDiagnostics(issues, philosophyDir) {
     issues.push({ id: 'philosophy', type: 'inspiration_source', severity: issue.severity, msg: issue.msg });
   }
 
-  // 实现部分拆解校验（防止 Weaver 跳过拆解步骤）
-  const decompositionCheck = validatePartDecomposition(philosophyDir);
-  for (const issue of decompositionCheck.issues) {
-    issues.push({ id: 'philosophy', type: 'part_decomposition', severity: issue.severity, msg: issue.msg });
-  }
 }
 
 function summarizeIssues(issues) {
@@ -403,7 +566,7 @@ export function contextSummary(versionDir, verificationsDir, philosophyDir) {
   const { issues } = doctor(versionDir, verificationsDir, philosophyDir);
 
   // 区分模板阶段问题（待填充）和真实损坏
-  const templateIssues = issues.filter((i) => i.is_template || i.type === 'intent_map_template' || i.type === 'inspiration_source' || i.type === 'part_decomposition');
+  const templateIssues = issues.filter((i) => i.is_template || i.type === 'intent_map_template' || i.type === 'inspiration_source');
   const realIssues = issues.filter((i) => !templateIssues.includes(i));
 
   const risks = [];
@@ -416,11 +579,12 @@ export function contextSummary(versionDir, verificationsDir, philosophyDir) {
 
   return {
     intent_map_valid: mapState.valid === true,
-    progress: {
+    progress: {
       completed: status.counts.completed,
       total: status.counts.total,
-      rate: `${status.counts.completed}/${status.counts.total}`,
-    },
+      rate: `${status.counts.completed}/${status.counts.total}`,
+    },
+    deprecated_intents: status.deprecated || [],
     next_intent: next ? next.id : null,
     pending_verifications: pending,
     inconsistent_states: issues.filter((i) => i.type === 'in_progress_no_record' || i.type === 'completed_no_record').map((i) => i.id),
@@ -440,7 +604,7 @@ export function contextSummary(versionDir, verificationsDir, philosophyDir) {
  * @param {string} intentId
  * @returns {object}
  */
-export function traceIntent(versionDir, verificationsDir, philosophyDir, intentId) {
+export function traceIntent(versionDir, verificationsDir, philosophyDir, intentId) {
   const intent = getIntent(versionDir, intentId);
   if (!intent) throw new Error(`Intent 不存在: ${intentId}`);
 
@@ -482,19 +646,51 @@ export function traceIntent(versionDir, verificationsDir, philosophyDir, intentI
       walkDeps(dep, depth + 1);
     }
   }
-  walkDeps(intentId, 0);
-
-  return {
-    intent,
+  walkDeps(intentId, 0);
+
+  const version = basename(versionDir);
+  const ref = formatIntentRef(version, intentId);
+  const loomRoot = dirname(versionDir);
+  const predecessors = (intent.lineage?.predecessors || []).map((item) => {
+    let revision = null;
+    try { revision = getIntent(join(loomRoot, item.version), item.intent_id).revision ?? 1; }
+    catch { /* Validation is structural; a referenced version may not be locally available. */ }
+    return { ...item, ref: formatIntentRef(item.version, item.intent_id), revision };
+  });
+  const successors = [];
+  for (const candidateVersion of readdirSync(loomRoot).filter((name) => /^v\d+$/.test(name))) {
+    const candidateDir = join(loomRoot, candidateVersion);
+    if (!statSync(candidateDir).isDirectory() || !existsSync(join(candidateDir, '04_INTENT_MAP.json'))) continue;
+    let candidateMap;
+    try { candidateMap = loadIntentMap(candidateDir); }
+    catch { continue; }
+    for (const [candidateId, candidate] of Object.entries(candidateMap.intents)) {
+      if (candidate.lineage?.predecessors?.some((item) => item.version === version && item.intent_id === intentId)) {
+        successors.push({
+          ref: formatIntentRef(candidateVersion, candidateId),
+          version: candidateVersion,
+          intent_id: candidateId,
+          revision: candidate.revision ?? 1,
+        });
+      }
+    }
+  }
+
+  return {
+    ref,
+    version,
+    revision: intent.revision ?? 1,
+    intent,
     narrative,
     narrative_error: narrativeError,
     acceptance,
     acceptance_error: acceptanceError,
     verification_history: verificationHistory,
-    philosophy_anchors_content: philosophyContent,
-    dependency_chain: dependencyChain,
-  };
-}
+    philosophy_anchors_content: philosophyContent,
+    dependency_chain: dependencyChain,
+    lineage: { predecessors, successors },
+  };
+}
 
 // ─── reverse-dep ───────────────────────────────────────
 // 反向依赖：哪些 Intent 依赖这个 Intent

package/cli/src/guide.js

@@ -5,8 +5,11 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { readCurrentPointer } from './version.js';
-import { loadIntentMap } from './intent-map.js';
-import { isAutoOn, getAutoMode, writeHeartbeat, needsHumanReview } from './auto.js';
+import { loadIntentMap } from './intent-map.js';
+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';
 
 /**
  * 检测文件是否还是模板（未填充真实内容）。
@@ -60,7 +63,7 @@ export function guideProject(projectDir, options = {}) {
       verify_command: 'loom guide',
     },
     need_philosophy: {
-      inputs: ['meta/PHILOSOPHY_WEAVER.md', 'meta/BASELINE.md', 'dimensions/PART_DECOMPOSITION.md', 'dimensions/SEARCH_METHODOLOGY.md'],
+      inputs: ['meta/PHILOSOPHY_WEAVER.md', 'meta/BASELINE.md', 'dimensions/SEARCH_METHODOLOGY.md'],
       outputs: [`.loom/${current}/00_PHILOSOPHY/PRODUCT_PHILOSOPHY.md`, `.loom/${current}/00_PHILOSOPHY/ENGINEERING_CREED.md`, `.loom/${current}/00_PHILOSOPHY/DECISION_RUBRIC.md`],
       verify_command: 'loom philosophy check',
     },
@@ -69,11 +72,26 @@ export function guideProject(projectDir, options = {}) {
       outputs: [`.loom/${current}/01_VISION.md`],
       verify_command: 'loom guide',
     },
-    need_architecture: {
-      inputs: ['roles/architect.md', `.loom/${current}/01_VISION.md`],
-      outputs: [`.loom/${current}/02_ARCHITECTURE.md`, `.loom/${current}/04_INTENT_MAP.json`],
-      verify_command: 'loom doctor',
-    },
+    need_architecture: {
+      inputs: ['roles/architect.md', `.loom/${current}/01_VISION.md`],
+      outputs: [`.loom/${current}/02_ARCHITECTURE.md`, `.loom/${current}/04_INTENT_MAP.json`],
+      verify_command: 'loom doctor',
+    },
+    need_capability_graph: {
+      inputs: ['roles/architect.md', `.loom/${current}/01_VISION.md`],
+      outputs: [`.loom/${current}/07_CAPABILITY_GRAPH.json`, `.loom/${current}/07_CAPABILITY_BRIEFS/`],
+      verify_command: 'loom capability coverage',
+    },
+    capability_graph_incomplete: {
+      inputs: ['roles/architect.md', `.loom/${current}/07_CAPABILITY_GRAPH.json`, `.loom/${current}/04_INTENT_MAP.json`],
+      outputs: [`.loom/${current}/07_CAPABILITY_GRAPH.json`, `.loom/${current}/07_CAPABILITY_BRIEFS/`],
+      verify_command: 'loom capability coverage',
+    },
+    capability_graph_proposals_pending: {
+      inputs: ['roles/architect.md', `.loom/${current}/07_GRAPH_PROPOSALS/`, `.loom/${current}/07_CAPABILITY_GRAPH.json`],
+      outputs: [`.loom/${current}/07_GRAPH_PROPOSALS/`, `.loom/${current}/07_CAPABILITY_GRAPH.json`, `.loom/${current}/04_INTENT_MAP.json`],
+      verify_command: 'loom capability proposal list',
+    },
     intent_map_broken: {
       inputs: [`.loom/${current}/04_INTENT_MAP.json`],
       outputs: [`.loom/${current}/04_INTENT_MAP.json`],
@@ -89,10 +107,10 @@ export function guideProject(projectDir, options = {}) {
       outputs: ['代码文件', `.loom/${current}/verifications/INT-*.json`],
       verify_command: 'loom verify pending',
     },
-    all_done: {
-      inputs: [],
-      outputs: [],
-      verify_command: 'loom doctor',
+    done: {
+      inputs: [`.loom/${current}/04_INTENT_MAP.json`, `.loom/${current}/verifications/`],
+      outputs: [`.loom/${current}/06_CHANGELOG.json`, `.loom/${current}/06_CHANGELOG.md`],
+      verify_command: 'loom doctor',
     },
     unknown: {
       inputs: [],
@@ -168,8 +186,9 @@ function diagnoseStage(cwd, loomRoot, auto) {
 
   const versionDir = join(loomRoot, current);
   const philosophyDir = join(versionDir, '00_PHILOSOPHY');
-  const visionPath = join(versionDir, '01_VISION.md');
-  const intentMapPath = join(versionDir, '04_INTENT_MAP.json');
+  const visionPath = join(versionDir, '01_VISION.md');
+  const intentMapPath = join(versionDir, '04_INTENT_MAP.json');
+  const capabilityGraphPath = join(versionDir, '07_CAPABILITY_GRAPH.json');
 
   // 状态 1: 哲学未织造
   const philosophyFile = join(philosophyDir, 'PRODUCT_PHILOSOPHY.md');
@@ -198,16 +217,77 @@ function diagnoseStage(cwd, loomRoot, auto) {
     };
   }
 
-  // 状态 3: 愿景已定义，Intent Map 未设计
-  if (isTemplate(intentMapPath)) {
-    return {
-      stage: 'need_architecture',
-      stage_num: 3,
-      details: { version: current },
-      auto,
-      next_action: '设计系统架构 + Intent Map',
-      next_command: 'loom activate architect',
-      message: `当前版本 ${current}：愿景已定义，Intent Map 还是模板，需要 Architect 设计。`,
+  // 状态 3: 愿景已定义，先展开项目问题面与能力缺口，再承诺 Intent。
+  if (existsSync(capabilityGraphPath) && isTemplate(capabilityGraphPath)) {
+    return {
+      stage: 'need_capability_graph',
+      stage_num: 3,
+      details: { version: current },
+      auto,
+      next_action: '展开 Capability Graph，路由高影响问题与能力缺口',
+      next_command: 'loom activate architect',
+      message: `当前版本 ${current}：愿景已定义，但 Capability Graph 还是模板。Architect 必须先判断哪些体验、系统、资产、风险与能力适用，再创建正式 Intent。`,
+    };
+  }
+
+  // 图谱一旦存在，就不能把不完整路由悄悄跨过去。旧项目缺少该文件仍保留兼容路径。
+  if (existsSync(capabilityGraphPath)) {
+    try {
+      const pendingProposals = listCapabilityProposals(versionDir, { unresolvedOnly: true });
+      if (pendingProposals.length) {
+        return {
+          stage: 'capability_graph_proposals_pending',
+          stage_num: 3,
+          details: { version: current, proposals: pendingProposals.map((proposal) => proposal.id) },
+          auto,
+          next_action: '审计新信息对 Capability Graph、Intent 和契约的影响',
+          next_command: 'loom capability proposal list',
+          message: `当前版本 ${current} 有 ${pendingProposals.length} 个未闭合的 Capability Graph proposal。它们是新要求、研究或实现发现，不得由 Forge 静默变成当前 Intent 范围。`,
+        };
+      }
+    } catch (error) {
+      return {
+        stage: 'capability_graph_proposals_pending', stage_num: 3, details: { version: current, error: error.message }, auto,
+        next_action: '修复 Capability Graph proposal', next_command: 'loom capability proposal list',
+        message: `Capability Graph proposal 无法审计: ${error.message}`,
+      };
+    }
+    try {
+      const coverage = getCapabilityCoverage(versionDir);
+      if (!coverage.summary.ready) {
+        return {
+          stage: 'capability_graph_incomplete',
+          stage_num: 3.1,
+          details: { version: current, coverage: coverage.summary },
+          auto,
+          next_action: '补齐 Capability Graph 的路由、可观察验证入口与 Intent 回链',
+          next_command: 'loom capability coverage',
+          message: `当前版本 ${current}：Capability Graph 尚未闭合（高影响前沿 ${coverage.summary.high_unrouted}、路由缺口 ${coverage.summary.routing_gaps}、不可观察 outcome ${coverage.summary.high_outcomes_without_observable_evidence}、未映射 Intent ${coverage.summary.unmapped_intents}）。先由 Architect 补图谱，再继续设计 Intent。`,
+        };
+      }
+    } catch (error) {
+      return {
+        stage: 'capability_graph_incomplete',
+        stage_num: 3.1,
+        details: { version: current, error: error.message },
+        auto,
+        next_action: '修复 Capability Graph',
+        next_command: 'loom capability coverage',
+        message: `Capability Graph 无法通过校验: ${error.message}`,
+      };
+    }
+  }
+
+  // 状态 3.5: 图谱已建立，Intent Map 未设计。
+  if (isTemplate(intentMapPath)) {
+    return {
+      stage: 'need_architecture',
+      stage_num: 3.5,
+      details: { version: current },
+      auto,
+      next_action: '从 Capability Graph 编译系统架构 + Intent Map',
+      next_command: 'loom activate architect',
+      message: `当前版本 ${current}：Capability Graph 已建立，Intent Map 还是模板。Architect 需要将已路由的问题面编译为系统架构与可闭合 Intent。`,
     };
   }
 
@@ -256,23 +336,58 @@ function diagnoseStage(cwd, loomRoot, auto) {
     };
   }
 
-  // 状态 6: 全部 completed
-  if (counts.completed === total && total > 0) {
-    return {
-      stage: 'done',
-      stage_num: 6,
-      details: { version: current, counts, total },
-      auto,
-      next_action: '项目阶段完成，考虑版本演进',
-      next_command: 'loom version new',
-      message: `当前版本 ${current}：全部 ${total} 个 Intent 已完成。可考虑 loom version new 开始新版本。`,
-    };
-  }
+  // 状态 6: 全部 completed
+  if (counts.completed === total && total > 0) {
+    const health = doctor(versionDir, join(versionDir, 'verifications'), philosophyDir);
+    const blocking = health.issues.filter((issue) => issue.severity === 'fatal' || issue.severity === 'high');
+    if (blocking.length) {
+      return {
+        stage: 'needs_review',
+        stage_num: 5.5,
+        details: { version: current, counts, blocking_issues: blocking.map((issue) => issue.type) },
+        auto,
+        next_action: '修复完成门或验证证据后重新运行 doctor',
+        next_command: 'loom doctor',
+        message: `当前版本 ${current} 的 Intent 均标为 completed，但健康检查仍有 ${blocking.length} 个高风险问题；不能宣告阶段完成。先运行 loom doctor。`,
+      };
+    }
+    const doneMessage = [
+      `当前版本 ${current}：全部 ${total} 个 Intent 已完成。`,
+      '',
+      '如果有新需求，先判断变更档位：',
+      '- Patch：不触及 Intent，只修 bug / 样式 / 实现细节；跑验证并记录 changelog。',
+      '- Minor：新增或修改 Intent，但不改变哲学前提、愿景北极星、架构边界；在当前版本内变更并重验受影响 Intent。',
+      '- Major：哲学前提、愿景北极星或架构边界变化；运行 loom version new。',
+    ].join('\n');
+    return {
+      stage: 'done',
+      stage_num: 6,
+      details: { version: current, counts, total },
+      auto,
+      next_action: '项目阶段完成，按 Patch / Minor / Major 判断下一步',
+      next_command: 'loom help version',
+      message: doneMessage,
+    };
+  }
 
-  // 状态 5: 有 in_progress
-  if (counts.in_progress > 0) {
-    const inProgressIds = allIntents.filter((i) => i.status === 'in_progress').map((i) => i.id);
-    return {
+  // 状态 5: 有 in_progress
+  if (counts.in_progress > 0) {
+    const inProgressIds = allIntents.filter((i) => i.status === 'in_progress').map((i) => i.id);
+    const atelierWithoutRecord = allIntents.find((intent) => intent.status === 'in_progress'
+      && intent.quality_strategy === 'atelier'
+      && !existsSync(join(versionDir, '09_ATELIER', `${intent.id}.json`)));
+    if (atelierWithoutRecord) {
+      return {
+        stage: 'in_loop',
+        stage_num: 5,
+        details: { version: current, counts, in_progress_ids: inProgressIds, atelier_intent: atelierWithoutRecord.id },
+        auto,
+        next_action: '创建 Atelier Record 并冻结基线',
+        next_command: `loom atelier init ${atelierWithoutRecord.id}`,
+        message: `${atelierWithoutRecord.id} 已进入 Atelier Path，但还没有唯一创作记录。先创建 Record，再按 Forge Context Pack 形成 Authorial Stance。`,
+      };
+    }
+    return {
       stage: 'in_loop',
       stage_num: 5,
       details: { version: current, counts, in_progress_ids: inProgressIds },