@haaaiawd/loom 0.9.0 → 1.0.0

package/cli/src/diagnostics.js

@@ -3,10 +3,14 @@
 // 全部是只读的数据聚合，不做决策、不修改文件。
 
 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';
 
 function readIntentMapRaw(versionDir) {
   const filePath = join(versionDir, '04_INTENT_MAP.json');
@@ -59,7 +63,7 @@ function intentMapDiagnostics(versionDir) {
 
   const isTemplate = raw._meta?._template === true;
   if (isTemplate) {
-    issues.push({ id: 'intent_map', type: 'intent_map_template', severity: 'high', msg: 'Intent Map 仍是模板，尚未由 Architect 产出真实意图图' });
+    issues.push({ id: 'intent_map', type: 'intent_map_template', severity: 'high', msg: 'Intent Map 仍是模板，尚未由 Architect 产出真实意图图', is_template: true });
   }
 
   try {
@@ -69,16 +73,12 @@ function intentMapDiagnostics(versionDir) {
     valid = false;
     // 模板状态下字段缺失是预期的，降级为 high 而非 fatal
     // 非模板状态下字段缺失是真正的损坏，保持 fatal
-    issues.push({ id: 'intent_map', type: 'intent_map_invalid', severity: isTemplate ? 'high' : 'fatal', msg: e.message });
+    issues.push({ id: 'intent_map', type: 'intent_map_invalid', severity: isTemplate ? 'high' : 'fatal', msg: e.message, is_template: isTemplate });
   }
 
   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, '')
@@ -87,6 +87,34 @@ function normalizeVerificationCommand(command) {
     .trim();
 }
 
+// 包管理器别名——npm test / pnpm test / bun test / yarn test 互相等价
+const PM_ALIASES = ['npm', 'pnpm', 'bun', 'yarn'];
+
+/**
+ * 把命令里的包管理器名归一化成 token，方便比较。
+ * "pnpm test" → "<PM> test"，"npm run build" → "<PM> run build"
+ */
+function normalizePackageManager(command) {
+  let result = command;
+  for (const pm of PM_ALIASES) {
+    result = result.replace(new RegExp(`\\b${pm}\\b`, 'g'), '<PM>');
+  }
+  return result;
+}
+
+/**
+ * 检测项目使用的包管理器。
+ * 优先级：锁文件存在性
+ * @param {string} projectDir — 项目根目录
+ * @returns {string} 'pnpm' | 'bun' | 'yarn' | 'npm'
+ */
+export function detectPackageManager(projectDir) {
+  if (existsSync(join(projectDir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(projectDir, 'bun.lockb'))) return 'bun';
+  if (existsSync(join(projectDir, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
 function commandCoversMethod(actualCommand, expectedMethod) {
   const actual = normalizeVerificationCommand(actualCommand);
   const expected = normalizeVerificationCommand(expectedMethod);
@@ -96,8 +124,12 @@ function commandCoversMethod(actualCommand, expectedMethod) {
     const expectedPart = normalizeVerificationCommand(part);
     if (!expectedPart) return true;
     if (actual.includes(expectedPart)) return true;
+    // 包管理器别名归一化：pnpm test = npm test = bun test = yarn test
+    const actualNorm = normalizePackageManager(actual);
+    const expectedNorm = normalizePackageManager(expectedPart);
+    if (actualNorm.includes(expectedNorm)) return true;
     // npm test is an acceptable broader reproduction for node --test based methods.
-    if (expectedPart.startsWith('node --test') && actual.includes('npm test')) return true;
+    if (expectedPart.startsWith('node --test') && actualNorm.includes('<PM> test')) return true;
     return false;
   });
 }
@@ -105,6 +137,48 @@ function commandCoversMethod(actualCommand, expectedMethod) {
 // ─── doctor ────────────────────────────────────────────
 // 全面健康检查：一致性 + 孤儿引用 + 循环依赖 + 僵尸 Intent
 
+// 每种 issue 类型的修复提示——给 Agent 行动化建议
+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 / 填必填字段）',
+  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',
+  cycle: '打破循环：把循环链中某个 Intent 的 depends_on 里去掉前驱，或拆成更小的 Intent',
+  zombie: '检查 {id} 是否还需要——不需要就 loom intent update {id} --status completed 或 blocked',
+  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 互相等价）',
+  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 生成投影',
+};
+
+/**
+ * 给 issue 补 fix_hint——把 {id} {dep} 等占位符替换成实际值。
+ */
+function addFixHint(issue) {
+  const template = FIX_HINTS[issue.type];
+  if (!template) return issue;
+  let hint = template;
+  // 提取 id 里的实际 Intent ID（issue.id 可能是 "INT-001" 或 "INT-002→INT-001" 等）
+  const idMatch = String(issue.id).match(/(INT-\d+)/);
+  if (idMatch) hint = hint.replace(/\{id\}/g, idMatch[1]);
+  // 提取 dep（从 msg 里找 depends_on 后的 Intent ID）
+  const depMatch = issue.msg && issue.msg.match(/依赖.*?(INT-\d+)/);
+  if (depMatch) hint = hint.replace(/\{dep\}/g, depMatch[1]);
+  return { ...issue, fix_hint: hint };
+}
+
 /**
  * 项目健康检查。
  * @param {string} versionDir — 当前版本目录
@@ -118,21 +192,55 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
 
   if (!mapState.validMap) {
     appendPhilosophyDiagnostics(issues, philosophyDir);
-    return { issues, summary: summarizeIssues(issues) };
+    const issuesWithHints = issues.map(addFixHint);
+    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 但无验证记录（可能上次中断）` });
-    }
-  }
+  // 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.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)) {
@@ -193,28 +301,29 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
 
   // 7. 验证脚本可执行性：检查 verification_method 引用的脚本/目录是否存在
   const projectDir = join(versionDir, '..', '..');
+  const pm = detectPackageManager(projectDir);
   for (const [id, intent] of Object.entries(intents)) {
     const vm = getIntentVerificationMethod(intent);
     if (!vm) continue;
-    // 检测 npm test 引用
-    if (vm.includes('npm test') || vm.includes('npm run test')) {
+    // 检测任意包管理器的 test 引用（npm/pnpm/bun/yarn）
+    const pmTestRe = new RegExp(`(?:${PM_ALIASES.join('|')})\\s+(?:run\\s+)?test`);
+    if (pmTestRe.test(vm)) {
       const pkgPath = join(projectDir, 'package.json');
       if (!existsSync(pkgPath)) {
-        issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 npm test 但项目根没有 package.json` });
+        issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 test 但项目根没有 package.json` });
       } else {
         try {
           const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
           const testScript = pkg.scripts && pkg.scripts.test;
           if (!testScript) {
-            issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 npm test 但 package.json 没有 test 脚本` });
+            issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 test 但 package.json 没有 test 脚本` });
           } else {
             // 检查 test 脚本引用的目录/文件是否存在
-            // 常见模式: "node --test test/" / "mocha test/" / "jest" 等
             const testDirMatch = testScript.match(/(?:--test|test)\s+(\S+)/);
             if (testDirMatch) {
               const testTarget = testDirMatch[1].replace(/['"]/g, '');
               if (!existsSync(join(projectDir, testTarget))) {
-                issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 npm test 但 test 脚本引用的 ${testTarget} 不存在` });
+                issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 test 但 test 脚本引用的 ${testTarget} 不存在` });
               }
             }
           }
@@ -242,13 +351,44 @@ 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);
-  return { issues, summary: summarizeIssues(issues) };
+  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) };
 }
 
 function appendPhilosophyDiagnostics(issues, philosophyDir) {
@@ -260,11 +400,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) {
@@ -331,25 +466,31 @@ export function contextSummary(versionDir, verificationsDir, philosophyDir) {
   const pending = mapState.valid ? getPendingVerifications(versionDir, verificationsDir) : [];
   const { issues } = doctor(versionDir, verificationsDir, philosophyDir);
 
+  // 区分模板阶段问题（待填充）和真实损坏
+  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 = [];
-  const fatalCount = issues.filter((i) => i.severity === 'fatal').length;
-  const highCount = issues.filter((i) => i.severity === 'high').length;
+  const fatalCount = realIssues.filter((i) => i.severity === 'fatal').length;
+  const highCount = realIssues.filter((i) => i.severity === 'high').length;
   if (fatalCount > 0) risks.push(`${fatalCount} 个致命问题（Intent Map 损坏/循环依赖）`);
   if (highCount > 0) risks.push(`${highCount} 个高严重度问题（状态不一致/孤儿引用）`);
+  if (templateIssues.length > 0) risks.push(`${templateIssues.length} 个待填充（模板未产出，需 Weaver/Architect 填充）`);
   if (status.counts.blocked > 0) risks.push(`${status.counts.blocked} 个阻塞 Intent`);
 
   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),
     risks,
-    healthy: issues.length === 0,
+    healthy: realIssues.length === 0,
   };
 }
 
@@ -364,7 +505,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}`);
 
@@ -406,19 +547,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,9 @@
 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, writeHeartbeat, needsHumanReview } from './auto.js';
+import { loadIntentMap } from './intent-map.js';
+import { isAutoOn, getAutoMode, writeHeartbeat, needsHumanReview } from './auto.js';
+import { doctor } from './diagnostics.js';
 
 /**
  * 检测文件是否还是模板（未填充真实内容）。
@@ -36,17 +37,78 @@ function isTemplate(filePath) {
 /**
  * 诊断项目当前阶段。
  * @param {string} projectDir — 项目根目录
- * @returns {{ stage: string, stage_num: number, details: object, auto: boolean, next_action: string, next_command: string, message: string, needs_human_review: boolean }}
- */
-export function guideProject(projectDir, options = {}) {
-  const cwd = projectDir || process.cwd();
-  const loomRoot = join(cwd, '.loom');
-  const auto = isAutoOn(loomRoot);
-  const result = diagnoseStage(cwd, loomRoot, auto);
-  // 统一后处理：写心跳 + 加 AUTO 提示词 + 判断是否需要人类 review
-  if (existsSync(loomRoot) && !options.dryRun) {
-    try {
-      writeHeartbeat(loomRoot, {
+ * @returns {{ stage: string, stage_num: number, details: object, auto: boolean, next_action: string, next_command: string, message: string, needs_human_review: boolean }}
+ */
+export function guideProject(projectDir, options = {}) {
+  const cwd = projectDir || process.cwd();
+  const loomRoot = join(cwd, '.loom');
+  const autoMode = getAutoMode(loomRoot);
+  const auto = autoMode !== 'manual'; // 向后兼容 boolean
+  const result = diagnoseStage(cwd, loomRoot, auto);
+  result.auto_mode = autoMode;
+
+  // 按 stage 补充可执行信息：要读什么、要产出什么、完成后跑什么校验
+  const current = result.details.version || 'v1';
+  const stageMeta = {
+    not_initialized: {
+      inputs: [],
+      outputs: ['.loom/v1/'],
+      verify_command: 'loom guide',
+    },
+    no_version: {
+      inputs: [],
+      outputs: ['.loom/v1/'],
+      verify_command: 'loom guide',
+    },
+    need_philosophy: {
+      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',
+    },
+    need_vision: {
+      inputs: ['roles/visionary.md', `.loom/${current}/00_PHILOSOPHY/`],
+      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',
+    },
+    intent_map_broken: {
+      inputs: [`.loom/${current}/04_INTENT_MAP.json`],
+      outputs: [`.loom/${current}/04_INTENT_MAP.json`],
+      verify_command: 'loom intent validate',
+    },
+    in_loop: {
+      inputs: ['roles/forge.md', 'roles/keeper.md', `.loom/${current}/04_INTENT_MAP.json`],
+      outputs: ['代码文件', `.loom/${current}/verifications/INT-*.json`],
+      verify_command: 'loom verify pending',
+    },
+    ready_for_loop: {
+      inputs: ['roles/forge.md', 'roles/keeper.md', `.loom/${current}/04_INTENT_MAP.json`],
+      outputs: ['代码文件', `.loom/${current}/verifications/INT-*.json`],
+      verify_command: 'loom verify pending',
+    },
+    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: [],
+      outputs: [],
+      verify_command: 'loom doctor',
+    },
+  };
+  const meta = stageMeta[result.stage] || {};
+  result.inputs = meta.inputs || [];
+  result.outputs = meta.outputs || [];
+  result.verify_command = meta.verify_command || null;
+  // 统一后处理：写心跳 + 加 AUTO 提示词 + 判断是否需要人类 review
+  if (existsSync(loomRoot) && !options.dryRun) {
+    try {
+      writeHeartbeat(loomRoot, {
         stage: result.stage,
         stage_num: result.stage_num,
         next_command: result.next_command,
@@ -57,13 +119,19 @@ export function guideProject(projectDir, options = {}) {
   result.needs_human_review = needsHumanReview(loomRoot, result.stage_num);
   // 在 message 末尾加 AUTO 提示
   if (result.stage_num > 0 && result.stage_num < 4) {
-    result.message += auto
-      ? '\n\n> ⚠ 这是设计阶段（哲学/愿景/架构），即使 AUTO 模式开启也需要人类 review 后再继续。'
-      : '\n\n> ⚠ AUTO 模式关闭——每步都需要人类确认后再继续。';
-  } else if (result.stage_num >= 4 && !auto) {
-    result.message += '\n\n> ⚠ AUTO 模式关闭——执行 next_command 后等人类确认再继续。';
-  } else if (result.stage_num >= 4 && auto) {
-    result.message += '\n\n> AUTO 模式开启——直接执行 next_command，无需人类确认。';
+    if (autoMode === 'auto-design') {
+      result.message += '\n\n> AUTO 模式 auto-design——设计阶段也自动执行，无需人类确认。';
+    } else if (autoMode === 'auto-loop') {
+      result.message += '\n\n> ⚠ 这是设计阶段（哲学/愿景/架构），auto-loop 模式下需要人类 review 后再继续。';
+    } else {
+      result.message += '\n\n> ⚠ AUTO 模式 manual——每步都需要人类确认后再继续。';
+    }
+  } else if (result.stage_num >= 4) {
+    if (auto) {
+      result.message += '\n\n> AUTO 模式开启——直接执行 next_command，无需人类确认。';
+    } else {
+      result.message += '\n\n> ⚠ AUTO 模式关闭——执行 next_command 后等人类确认再继续。';
+    }
   }
   return result;
 }
@@ -145,11 +213,11 @@ function diagnoseStage(cwd, loomRoot, auto) {
   }
 
   // 状态 4-7: Intent Map 已设计，根据 Intent 状态判断
-  let intentMap;
-  let intents;
-  try {
-    intentMap = loadIntentMap(versionDir);
-    intents = intentMap.intents;
+  let intentMap;
+  let intents;
+  try {
+    intentMap = loadIntentMap(versionDir);
+    intents = intentMap.intents;
   } catch (e) {
     return {
       stage: 'intent_map_broken',
@@ -189,18 +257,39 @@ 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) {
@@ -220,7 +309,7 @@ function diagnoseStage(cwd, loomRoot, auto) {
   if (counts.needs_review > 0) {
     const reviewIds = allIntents.filter((i) => i.status === 'needs_review').map((i) => i.id);
     // 读 _meta.pass_count 收敛趟计数（最大 3 趟）
-    const passCount = intentMap._meta?.pass_count || 1;
+    const passCount = intentMap._meta?.pass_count || 1;
     const MAX_PASSES = 3;
     const isOverLimit = passCount > MAX_PASSES;
     const passMsg = ` [Pass ${passCount}/${MAX_PASSES}]`;