@haaaiawd/loom 0.1.0 → 0.7.0

package/cli/help/workflow.md

@@ -0,0 +1,94 @@
+## LOOM 工作流
+
+从零到交付的完整流程。每个阶段有明确的产出和验收标准。
+
+## 第一步：诊断当前阶段
+
+\`\`\`bash
+loom guide
+\`\`\`
+
+guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
+Agent 每完成一步都跑 guide 确认下一步。
+
+## AUTO 模式
+
+\`\`\`bash
+loom auto on      # 开启：Agent 自动连续执行，不等确认
+loom auto off     # 关闭：每步需要用户确认
+\`\`\`
+
+AUTO on 时 Agent 一路跑到底，跑完生成 preview 给人看。
+AUTO off 时每步停下等用户说继续。
+
+## 阶段 1：织造哲学（Weaver）
+
+\`\`\`bash
+loom activate weaver
+\`\`\`
+
+Weaver 根据项目特征从真实思想体系织造定制化哲学。产出：
+- PRODUCT_PHILOSOPHY.md — 产品价值观、反模式清单、决策取舍规则
+- ENGINEERING_CREED.md — 工程原则（按需）
+- DECISION_RUBRIC.md — 冲突时的优先级（按需）
+- PROJECT_BASELINE.md — 项目特定底线（按需）
+
+**验收**：哲学有北极星、有反模式、有决策标准。全是空话就重做。
+
+## 阶段 2：定义愿景（Visionary）
+
+\`\`\`bash
+loom activate visionary
+\`\`\`
+
+基于哲学定义产品愿景，为每个 Intent 写意图叙事（"为什么存在"）。产出：
+- 01_VISION.md — 北极星 + 意图叙事列表
+
+**验收**：叙事是"为什么"不是"做什么"。写成功能列表就重做。
+
+## 阶段 3：设计系统（Architect）
+
+\`\`\`bash
+loom activate architect
+\`\`\`
+
+基于愿景设计系统结构，绘制 Intent Map。产出：
+- 02_ARCHITECTURE.md — 系统设计
+- 04_INTENT_MAP.json — Intent 依赖图 + 验收契约 + 哲学锚点
+
+**验收**：验收契约具体到可验证，依赖无环，每个 Intent 有叙事引用。
+跑 \`loom intent validate\` 校验结构，跑 \`loom doctor\` 检查完整性。
+
+## 阶段 4：Intent Loop
+
+\`\`\`bash
+loom activate keeper    # Keeper 选 Intent、验证
+loom activate forge     # Forge 实现
+loom intent next        # 下一个可执行 Intent
+loom context            # 当前状态摘要
+\`\`\`
+
+每个 Intent 独立走一圈：选 → 实现 → 验证 → 闭合或修正。
+详细流程见 \`loom help loop\`。
+
+## 阶段 5：人类预览
+
+\`\`\`bash
+loom preview
+\`\`\`
+
+输出提示词，Agent 按提示词读 .loom/ 文件、拆解信息、生成 HTML 可视化预览。
+人类用浏览器打开 HTML 看全局——哲学、愿景、架构、Intent 进度、验证历史。
+这是只读投影，修改请编辑源文件后重新生成。
+
+## 阶段 6：版本演进（按需）
+
+当哲学前提/愿景北极星/架构边界变了，需要 Major 升级。
+详细流程见 \`loom help version\`。
+
+## 核心原则
+
+- **哲学是经线，意图是纬线** — 所有角色共享哲学锚点
+- **底线不可协商** — BASELINE 5 条 + 项目特定底线，角色激活时强制加载
+- **意图可回溯** — 每个 Intent 携带叙事，Keeper 独立验证忠实度
+- **文档开销不超过开发开销** — 小项目可以粗粒度，不必教条

package/cli/src/activate.js

@@ -4,13 +4,10 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getLoomRoot } from './shared/paths.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-function getLoomRoot() {
-  return resolve(__dirname, '..', '..');
-}
-
 /** 合法角色名 */
 const VALID_ROLES = ['weaver', 'visionary', 'architect', 'forge', 'keeper'];
 
@@ -26,10 +23,10 @@ const ROLE_FILES = {
 /**
  * 输出角色激活提示词。
  * @param {string} role — 角色名
- * @param {string} loomDir — .loom/v{N} 目录（可选，weaver 不需要）
+ * @param {string} versionDir — .loom/v{N} 目录（可选，weaver 不需要）
  * @returns {string} 激活提示词
  */
-export function activateRole(role, loomDir) {
+export function activateRole(role, versionDir) {
   if (!VALID_ROLES.includes(role)) {
     throw new Error(`未知角色: ${role}\n合法角色: ${VALID_ROLES.join(', ')}`);
   }
@@ -44,13 +41,25 @@ export function activateRole(role, loomDir) {
   }
   parts.push(readFileSync(roleFile, 'utf-8'));
 
-  // 2. BASELINE（所有角色都需要）
-  const baselineFile = join(loomRoot, 'meta/BASELINE.md');
-  parts.push('\n---\n\n## 强制加载：BASELINE\n\n' + readFileSync(baselineFile, 'utf-8'));
+  // 2. BASELINE 摘要（不重复全文——全文见 meta/BASELINE.md）
+  //    5 条底线压缩成摘要，角色需要知道底线存在 + 一句话内容。
+  //    如果角色需要底线细节（如 Weaver 织造哲学时），自行 readFileSync 全文。
+  parts.push('\n---\n\n## 强制加载：BASELINE 摘要\n\n');
+  parts.push('> 完整底线见 `meta/BASELINE.md`。以下是 5 条底线的摘要——\n');
+  parts.push('> 角色激活时必须知道这些底线存在，违反任何一条必须立即停止。\n');
+  parts.push('> Philosophy Weaver 织造哲学时必须读取完整 BASELINE.md 作为硬约束输入。\n\n');
+  parts.push('| 编号 | 底线 | 一句话 |\n');
+  parts.push('|------|------|--------|\n');
+  parts.push('| B1 | 必须有结构设计 | 编码前必须有明确的目录结构 + 模块职责边界 + 显式依赖关系 |\n');
+  parts.push('| B2 | 禁止硬编码 | 密钥/配置/环境特定值/魔法数字不进代码，用环境变量或集中配置 |\n');
+  parts.push('| B3 | 接口契约必须显式 | API/CLI/配置/错误语义/跨系统协议必须有显式定义，变更可追溯 |\n');
+  parts.push('| B4 | 决策必须可追溯 | 影响架构/接口/技术栈/依赖的决策必须记录（ADR 或等效格式） |\n');
+  parts.push('| B5 | 意图必须可回溯 | 每个实现单元有意图叙事（"为什么存在"），可被 Keeper 引用对照 |\n');
+  parts.push('\n> 底线不可被哲学覆盖。如果织造的哲学与底线冲突，底线优先。\n');
 
-  // 3. 项目特定底线（如果有 loomDir）
-  if (loomDir) {
-    const projectBaseline = join(loomDir, '00_PHILOSOPHY/PROJECT_BASELINE.md');
+  // 3. 项目特定底线（如果有 versionDir）
+  if (versionDir) {
+    const projectBaseline = join(versionDir, '00_PHILOSOPHY/PROJECT_BASELINE.md');
     if (existsSync(projectBaseline)) {
       parts.push('\n---\n\n## 强制加载：项目特定底线\n\n' + readFileSync(projectBaseline, 'utf-8'));
     }

package/cli/src/auto.js

@@ -1,6 +1,8 @@
-// auto — AUTO 模式开关
+// auto — AUTO 模式开关 + 心跳机制
 // 存储机制：.loom/auto 文件存在 = on，不存在 = off
-// 影响 guide 输出语气和 Agent 行为：on 时直接跑，off 时等确认
+// 心跳：每次 guide 调用时写 .loom/heartbeat.json（时间戳 + stage + next_command）
+// AUTO on（默认）：stage 4+（Intent Loop）自动跑，stage 1-3（哲学/愿景/架构）仍需人类 review
+// AUTO off：所有阶段都需人类确认，每步拆得更碎
 
 import { existsSync, writeFileSync, unlinkSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -34,11 +36,58 @@ export function autoOff(loomRoot) {
 /**
  * 获取 AUTO 状态描述。
  * @param {string} loomRoot — .loom 目录路径
- * @returns {{ on: boolean, since: string|null }}
+ * @returns {{ on: boolean, since: string|null, heartbeat: object|null }}
  */
 export function autoStatus(loomRoot) {
   const path = join(loomRoot, 'auto');
-  if (!existsSync(path)) return { on: false, since: null };
+  if (!existsSync(path)) return { on: false, since: null, heartbeat: null };
   const since = readFileSync(path, 'utf-8').trim();
-  return { on: true, since };
+  const heartbeat = readHeartbeat(loomRoot);
+  return { on: true, since, heartbeat };
+}
+
+/**
+ * 写入心跳——每次 guide 调用时记录当前状态。
+ * @param {string} loomRoot — .loom 目录路径
+ * @param {{ stage: string, stage_num: number, next_command: string, next_action: string }} info
+ */
+export function writeHeartbeat(loomRoot, info) {
+  const heartbeat = {
+    timestamp: new Date().toISOString(),
+    stage: info.stage,
+    stage_num: info.stage_num,
+    next_command: info.next_command,
+    next_action: info.next_action,
+  };
+  writeFileSync(join(loomRoot, 'heartbeat.json'), JSON.stringify(heartbeat, null, 2), 'utf-8');
+}
+
+/**
+ * 读取心跳。
+ * @param {string} loomRoot — .loom 目录路径
+ * @returns {object|null}
+ */
+export function readHeartbeat(loomRoot) {
+  const path = join(loomRoot, 'heartbeat.json');
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 判断当前阶段是否需要人类 review。
+ * AUTO on 时：stage 1-3（哲学/愿景/架构）需要人类 review，stage 4+ 自动跑
+ * AUTO off 时：所有阶段都需要人类 review
+ * @param {string} loomRoot — .loom 目录路径
+ * @param {number} stageNum — 阶段号
+ * @returns {boolean} 是否需要人类 review
+ */
+export function needsHumanReview(loomRoot, stageNum) {
+  const autoOn = isAutoOn(loomRoot);
+  if (!autoOn) return true; // AUTO off：所有阶段都需人类 review
+  // AUTO on：stage 1-3 需人类 review，stage 4+ 自动
+  return stageNum > 0 && stageNum < 4;
 }

package/cli/src/diagnostics.js

@@ -13,13 +13,13 @@ import { getVerificationHistory, getPendingVerifications, getVerificationContrac
 
 /**
  * 项目健康检查。
- * @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);
+export function doctor(versionDir, verificationsDir, philosophyDir) {
+  const { intents, topo_order } = loadIntentMap(versionDir);
   const issues = [];
 
   // 1. 状态一致性：in_progress/completed 但无验证记录
@@ -67,8 +67,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,6 +90,40 @@ export function doctor(loomDir, verificationsDir, philosophyDir) {
     }
   }
 
+  // 7. 验证脚本可执行性：检查 verification_method 引用的脚本/目录是否存在
+  const projectDir = join(versionDir, '..', '..');
+  for (const [id, intent] of Object.entries(intents)) {
+    if (!intent.verification_method) continue;
+    const vm = intent.verification_method;
+    // 检测 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 的职责
+        }
+      }
+    }
+  }
+
   const summary = {
     total_issues: issues.length,
     fatal: issues.filter((i) => i.severity === 'fatal').length,
@@ -143,16 +177,16 @@ 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 status = getStatus(versionDir);
+  const next = getNextIntent(versionDir);
+  const pending = getPendingVerifications(versionDir, verificationsDir);
+  const { issues } = doctor(versionDir, verificationsDir, philosophyDir);
 
   const risks = [];
   const fatalCount = issues.filter((i) => i.severity === 'fatal').length;
@@ -180,23 +214,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 +252,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 +267,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 +281,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 +301,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) {
   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)) {
+    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 提示词）。
+ */
+function diagnoseStage(cwd, loomRoot, auto) {
 
   // 状态 0: 没有 .loom/
   if (!existsSync(loomRoot)) {
@@ -137,6 +173,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 +183,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 +214,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 = intents._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 {