@haaaiawd/loom 0.1.0 → 0.8.0

package/cli/src/diagnostics.js

@@ -2,25 +2,123 @@
 // 提供 doctor / context / trace / reverse-dep / reverse-ref 五个聚合命令。
 // 全部是只读的数据聚合，不做决策、不修改文件。
 
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import { loadIntentMap, getStatus, getNextIntent, getNarrative, getIntent } from './intent-map.js';
-import { getPhilosophy } from './philosophy.js';
-import { getVerificationHistory, getPendingVerifications, getVerificationContract } from './verify.js';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { 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';
+
+function readIntentMapRaw(versionDir) {
+  const filePath = join(versionDir, '04_INTENT_MAP.json');
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+function summarizeRawIntentMap(data) {
+  const intents = data?.intents && typeof data.intents === 'object' ? data.intents : {};
+  const ids = { pending: [], in_progress: [], completed: [], blocked: [], needs_review: [] };
+  const titles = {};
+
+  for (const [id, intent] of Object.entries(intents)) {
+    const status = intent?.status;
+    if (ids[status]) ids[status].push(id);
+    titles[id] = intent?.title || '';
+  }
+
+  return {
+    counts: {
+      pending: ids.pending.length,
+      in_progress: ids.in_progress.length,
+      completed: ids.completed.length,
+      blocked: ids.blocked.length,
+      needs_review: ids.needs_review.length,
+      total: Object.keys(intents).length,
+    },
+    ids,
+    titles,
+  };
+}
+
+function intentMapDiagnostics(versionDir) {
+  const issues = [];
+  let raw = null;
+  let valid = null;
+  let validMap = null;
+
+  try {
+    raw = readIntentMapRaw(versionDir);
+  } catch (e) {
+    issues.push({ id: 'intent_map', type: 'intent_map_unreadable', severity: 'fatal', msg: `Intent Map 无法读取或 JSON 损坏: ${e.message}` });
+    return { raw, valid, issues, validMap: null };
+  }
+
+  if (!raw) {
+    issues.push({ id: 'intent_map', type: 'intent_map_missing', severity: 'fatal', msg: '缺少 04_INTENT_MAP.json' });
+    return { raw, valid, issues, validMap: null };
+  }
+
+  if (raw._meta?._template === true) {
+    issues.push({ id: 'intent_map', type: 'intent_map_template', severity: 'high', msg: 'Intent Map 仍是模板，尚未由 Architect 产出真实意图图' });
+  }
+
+  try {
+    validMap = loadIntentMap(versionDir);
+    valid = true;
+  } catch (e) {
+    valid = false;
+    issues.push({ id: 'intent_map', type: 'intent_map_invalid', severity: 'fatal', msg: e.message });
+  }
+
+  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, '')
+    .replace(/^\s*exec\s+/i, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function commandCoversMethod(actualCommand, expectedMethod) {
+  const actual = normalizeVerificationCommand(actualCommand);
+  const expected = normalizeVerificationCommand(expectedMethod);
+  if (!actual || !expected) return false;
+
+  return expected.split('&&').every((part) => {
+    const expectedPart = normalizeVerificationCommand(part);
+    if (!expectedPart) return true;
+    if (actual.includes(expectedPart)) 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;
+    return false;
+  });
+}
 
 // ─── doctor ────────────────────────────────────────────
 // 全面健康检查：一致性 + 孤儿引用 + 循环依赖 + 僵尸 Intent
 
 /**
  * 项目健康检查。
- * @param {string} loomDir — 当前版本目录
+ * @param {string} versionDir — 当前版本目录
  * @param {string} verificationsDir — 验证记录目录
  * @param {string} philosophyDir — 哲学目录
  * @returns {{ issues: object[], summary: object }}
  */
-export function doctor(loomDir, verificationsDir, philosophyDir) {
-  const { intents, topo_order } = loadIntentMap(loomDir);
-  const issues = [];
+export function doctor(versionDir, verificationsDir, philosophyDir) {
+  const mapState = intentMapDiagnostics(versionDir);
+  const issues = [...mapState.issues];
+
+  if (!mapState.validMap) {
+    appendPhilosophyDiagnostics(issues, philosophyDir);
+    return { issues, summary: summarizeIssues(issues) };
+  }
+
+  const { intents } = mapState.validMap;
 
   // 1. 状态一致性：in_progress/completed 但无验证记录
   for (const [id, intent] of Object.entries(intents)) {
@@ -67,8 +165,8 @@ export function doctor(loomDir, verificationsDir, philosophyDir) {
   for (const [id, intent] of Object.entries(intents)) {
     if (intent.status !== 'in_progress' && intent.status !== 'blocked') continue;
     const recordPath = join(verificationsDir, `${id}.json`);
-    let lastActivity = existsSync(join(loomDir, '04_INTENT_MAP.json'))
-      ? statSync(join(loomDir, '04_INTENT_MAP.json')).mtimeMs
+    let lastActivity = existsSync(join(versionDir, '04_INTENT_MAP.json'))
+      ? statSync(join(versionDir, '04_INTENT_MAP.json')).mtimeMs
       : now;
     if (existsSync(recordPath)) {
       lastActivity = Math.max(lastActivity, statSync(recordPath).mtimeMs);
@@ -90,16 +188,91 @@ export function doctor(loomDir, verificationsDir, philosophyDir) {
     }
   }
 
-  const summary = {
-    total_issues: issues.length,
-    fatal: issues.filter((i) => i.severity === 'fatal').length,
-    high: issues.filter((i) => i.severity === 'high').length,
-    medium: issues.filter((i) => i.severity === 'medium').length,
-    healthy: issues.length === 0,
-  };
-
-  return { issues, summary };
-}
+  // 7. 验证脚本可执行性：检查 verification_method 引用的脚本/目录是否存在
+  const projectDir = join(versionDir, '..', '..');
+  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')) {
+      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` });
+      } 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 脚本` });
+          } 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} 不存在` });
+              }
+            }
+          }
+        } catch {
+          // package.json 解析失败，不报——不是 doctor 的职责
+        }
+      }
+    }
+  }
+
+  // 8. completed Intent 的 verification_method 必须被最新验证记录覆盖，防止契约命令漂移。
+  for (const [id, intent] of Object.entries(intents)) {
+    if (intent.status !== 'completed') continue;
+    const method = getIntentVerificationMethod(intent);
+    if (!method) continue;
+
+    const expected = normalizeVerificationCommand(method);
+    if (!expected || expected === 'human_review') continue;
+
+    const history = getVerificationHistory(verificationsDir, id);
+    const latest = history?.records?.[history.records.length - 1];
+    const actual = normalizeVerificationCommand(latest?.reproduction_command);
+
+    if (!latest) {
+      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)) {
+      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) };
+}
+
+function appendPhilosophyDiagnostics(issues, philosophyDir) {
+  // 哲学灵感来源校验（防止 Weaver 从训练数据"背"几个名字就交差）
+  if (!existsSync(philosophyDir)) return;
+
+  const inspirationCheck = validateInspirationSources(philosophyDir);
+  for (const issue of inspirationCheck.issues) {
+    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) {
+  return {
+    total_issues: issues.length,
+    fatal: issues.filter((i) => i.severity === 'fatal').length,
+    high: issues.filter((i) => i.severity === 'high').length,
+    medium: issues.filter((i) => i.severity === 'medium').length,
+    healthy: issues.length === 0,
+  };
+}
 
 /**
  * DFS 检测循环依赖。
@@ -143,29 +316,31 @@ function detectCycles(intents) {
 
 /**
  * 项目上下文摘要——Agent 重启后一条命令获取"我在哪"。
- * @param {string} loomDir
+ * @param {string} versionDir
  * @param {string} verificationsDir
  * @param {string} philosophyDir
  * @returns {object}
  */
-export function contextSummary(loomDir, verificationsDir, philosophyDir) {
-  const status = getStatus(loomDir);
-  const next = getNextIntent(loomDir);
-  const pending = getPendingVerifications(loomDir, verificationsDir);
-  const { issues } = doctor(loomDir, verificationsDir, philosophyDir);
+export function contextSummary(versionDir, verificationsDir, philosophyDir) {
+  const mapState = intentMapDiagnostics(versionDir);
+  const status = mapState.valid ? getStatus(versionDir) : summarizeRawIntentMap(mapState.raw);
+  const next = mapState.valid ? getNextIntent(versionDir) : null;
+  const pending = mapState.valid ? getPendingVerifications(versionDir, verificationsDir) : [];
+  const { issues } = doctor(versionDir, verificationsDir, philosophyDir);
 
   const risks = [];
   const fatalCount = issues.filter((i) => i.severity === 'fatal').length;
   const highCount = issues.filter((i) => i.severity === 'high').length;
-  if (fatalCount > 0) risks.push(`${fatalCount} 个致命问题（循环依赖）`);
-  if (highCount > 0) risks.push(`${highCount} 个高严重度问题（状态不一致/孤儿引用）`);
-  if (status.counts.blocked > 0) risks.push(`${status.counts.blocked} 个阻塞 Intent`);
-
-  return {
-    progress: {
-      completed: status.counts.completed,
-      total: status.counts.total,
-      rate: `${status.counts.completed}/${status.counts.total}`,
+  if (fatalCount > 0) risks.push(`${fatalCount} 个致命问题（Intent Map 损坏/循环依赖）`);
+  if (highCount > 0) risks.push(`${highCount} 个高严重度问题（状态不一致/孤儿引用）`);
+  if (status.counts.blocked > 0) risks.push(`${status.counts.blocked} 个阻塞 Intent`);
+
+  return {
+    intent_map_valid: mapState.valid === true,
+    progress: {
+      completed: status.counts.completed,
+      total: status.counts.total,
+      rate: `${status.counts.completed}/${status.counts.total}`,
     },
     next_intent: next ? next.id : null,
     pending_verifications: pending,
@@ -180,23 +355,27 @@ export function contextSummary(loomDir, verificationsDir, philosophyDir) {
 
 /**
  * 返回某个 Intent 的完整追溯链。
- * @param {string} loomDir
+ * @param {string} versionDir
  * @param {string} verificationsDir
  * @param {string} philosophyDir
  * @param {string} intentId
  * @returns {object}
  */
-export function traceIntent(loomDir, verificationsDir, philosophyDir, intentId) {
-  const intent = getIntent(loomDir, intentId);
+export function traceIntent(versionDir, verificationsDir, philosophyDir, intentId) {
+  const intent = getIntent(versionDir, intentId);
   if (!intent) throw new Error(`Intent 不存在: ${intentId}`);
 
   // 意图叙事
   let narrative = null;
-  try { narrative = getNarrative(loomDir, intentId); } catch { /* narrative_ref 可能缺失 */ }
+  let narrativeError = null;
+  try { narrative = getNarrative(versionDir, intentId); }
+  catch (e) { narrativeError = e.message; /* narrative_ref 可能缺失或解析失败 */ }
 
   // 验收契约
   let acceptance = null;
-  try { acceptance = getVerificationContract(loomDir, intentId); } catch { /* 可能缺失 */ }
+  let acceptanceError = null;
+  try { acceptance = getVerificationContract(versionDir, intentId); }
+  catch (e) { acceptanceError = e.message; /* 引用可能缺失或解析失败 */ }
 
   // 验证历史
   const verificationHistory = getVerificationHistory(verificationsDir, intentId);
@@ -214,7 +393,7 @@ export function traceIntent(loomDir, verificationsDir, philosophyDir, intentId)
   }
 
   // 依赖链（递归向上）
-  const { intents } = loadIntentMap(loomDir);
+  const { intents } = loadIntentMap(versionDir);
   const dependencyChain = [];
   function walkDeps(id, depth) {
     const node = intents[id];
@@ -229,7 +408,9 @@ export function traceIntent(loomDir, verificationsDir, philosophyDir, intentId)
   return {
     intent,
     narrative,
+    narrative_error: narrativeError,
     acceptance,
+    acceptance_error: acceptanceError,
     verification_history: verificationHistory,
     philosophy_anchors_content: philosophyContent,
     dependency_chain: dependencyChain,
@@ -241,12 +422,12 @@ export function traceIntent(loomDir, verificationsDir, philosophyDir, intentId)
 
 /**
  * 返回依赖指定 Intent 的所有 Intent。
- * @param {string} loomDir
+ * @param {string} versionDir
  * @param {string} intentId
  * @returns {string[]}
  */
-export function reverseDep(loomDir, intentId) {
-  const { intents } = loadIntentMap(loomDir);
+export function reverseDep(versionDir, intentId) {
+  const { intents } = loadIntentMap(versionDir);
   const result = [];
   for (const [id, intent] of Object.entries(intents)) {
     if (intent.depends_on?.includes(intentId)) {
@@ -261,12 +442,12 @@ export function reverseDep(loomDir, intentId) {
 
 /**
  * 返回引用指定哲学锚点的所有 Intent。
- * @param {string} loomDir
+ * @param {string} versionDir
  * @param {string} anchor — 如 "PRODUCT_PHILOSOPHY.md#core-belief"
  * @returns {string[]}
  */
-export function reverseRef(loomDir, anchor) {
-  const { intents } = loadIntentMap(loomDir);
+export function reverseRef(versionDir, anchor) {
+  const { intents } = loadIntentMap(versionDir);
   const result = [];
   for (const [id, intent] of Object.entries(intents)) {
     if (intent.philosophy_anchors?.includes(anchor)) {

package/cli/src/guide.js

@@ -6,11 +6,12 @@ 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 } from './auto.js';
+import { isAutoOn, writeHeartbeat, needsHumanReview } from './auto.js';
 
 /**
  * 检测文件是否还是模板（未填充真实内容）。
- * MD 文件检查 <!-- LOOM_TEMPLATE --> 标记。
+ * MD 文件检查 <!-- LOOM_TEMPLATE --> 标记——但如果文件已经超过模板大小（>2KB），
+ * 认为用户已经填充了真实内容只是忘了删标记，忽略标记。
  * JSON 文件检查 _meta._template 字段。
  */
 function isTemplate(filePath) {
@@ -24,18 +25,53 @@ function isTemplate(filePath) {
       return false; // 损坏文件不算模板
     }
   }
-  return content.includes('<!-- LOOM_TEMPLATE -->');
+  // MD 文件：有 LOOM_TEMPLATE 标记 且 文件较小（<2KB）才算模板。
+  // 如果文件已经 >2KB，说明用户填充了内容只是忘了删标记——忽略标记。
+  if (content.includes('<!-- LOOM_TEMPLATE -->')) {
+    return content.length < 2048;
+  }
+  return false;
 }
 
 /**
  * 诊断项目当前阶段。
  * @param {string} projectDir — 项目根目录
- * @returns {{ stage: string, stage_num: number, details: object, auto: boolean, next_action: string, next_command: string, message: string }}
+ * @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, {
+        stage: result.stage,
+        stage_num: result.stage_num,
+        next_command: result.next_command,
+        next_action: result.next_action,
+      });
+    } catch { /* 心跳写入失败不阻塞 guide */ }
+  }
+  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，无需人类确认。';
+  }
+  return result;
+}
+
+/**
+ * 内部函数：诊断阶段（不含心跳和 AUTO 提示词）。
  */
-export function guideProject(projectDir) {
-  const cwd = projectDir || process.cwd();
-  const loomRoot = join(cwd, '.loom');
-  const auto = isAutoOn(loomRoot);
+function diagnoseStage(cwd, loomRoot, auto) {
 
   // 状态 0: 没有 .loom/
   if (!existsSync(loomRoot)) {
@@ -109,9 +145,11 @@ export function guideProject(projectDir) {
   }
 
   // 状态 4-7: Intent Map 已设计，根据 Intent 状态判断
-  let intents;
-  try {
-    intents = loadIntentMap(versionDir).intents;
+  let intentMap;
+  let intents;
+  try {
+    intentMap = loadIntentMap(versionDir);
+    intents = intentMap.intents;
   } catch (e) {
     return {
       stage: 'intent_map_broken',
@@ -137,6 +175,9 @@ export function guideProject(projectDir) {
   // 状态 7: 有 blocked（优先报告）
   if (counts.blocked > 0) {
     const blockedIds = allIntents.filter((i) => i.status === 'blocked').map((i) => i.id);
+    const msg = auto
+      ? `有 ${counts.blocked} 个 Intent 阻塞: ${blockedIds.join(', ')}。AUTO 模式下这是唯一允许停下的情况——需要人工介入解决阻塞后才能继续。`
+      : `有 ${counts.blocked} 个 Intent 阻塞: ${blockedIds.join(', ')}。需要人工介入。`;
     return {
       stage: 'blocked',
       stage_num: 7,
@@ -144,7 +185,7 @@ export function guideProject(projectDir) {
       auto,
       next_action: '人工介入解决阻塞',
       next_command: 'loom intent get ' + blockedIds[0],
-      message: `有 ${counts.blocked} 个 Intent 阻塞: ${blockedIds.join(', ')}。需要人工介入。`,
+      message: msg,
     };
   }
 
@@ -175,6 +216,36 @@ export function guideProject(projectDir) {
     };
   }
 
+  // 状态 5.5: 有 needs_review（收敛趟）——已完成但需要重新验证的 Intent
+  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 MAX_PASSES = 3;
+    const isOverLimit = passCount > MAX_PASSES;
+    const passMsg = ` [Pass ${passCount}/${MAX_PASSES}]`;
+    if (isOverLimit) {
+      return {
+        stage: 'cannot_converge',
+        stage_num: 7,
+        details: { version: current, counts, needs_review_ids: reviewIds, pass_count: passCount },
+        auto,
+        next_action: '收敛失败——超过最大趟数，需 Architect 介入',
+        next_command: 'loom intent update ' + reviewIds[0] + ' --status blocked',
+        message: `当前版本 ${current}：收敛失败，已超过最大 ${MAX_PASSES} 趟限制（当前 Pass ${passCount}）。${counts.needs_review} 个 Intent 仍需重新验证（${reviewIds.join(', ')}）。这是系统性问题——需 Architect 介入重新设计。`,
+      };
+    }
+    return {
+      stage: 'converging',
+      stage_num: 5.5,
+      details: { version: current, counts, needs_review_ids: reviewIds, pass_count: passCount },
+      auto,
+      next_action: `进入收敛趟 Pass ${passCount}——重验 needs_review 的 Intent`,
+      next_command: 'loom intent update ' + reviewIds[0] + ' --status in_progress',
+      message: `当前版本 ${current}${passMsg}：${counts.needs_review} 个 Intent 需要重新验证（${reviewIds.join(', ')}）。这是不动点收敛的第 ${passCount} 趟——重验这些 Intent，通过则 completed，偏离则修正。一趟无新 needs_review 即收敛达成。最大 ${MAX_PASSES} 趟，超过判定为系统性问题。`,
+    };
+  }
+
   // 状态 4: 有 pending，进入 Intent Loop
   if (counts.pending > 0) {
     return {