@haaaiawd/loom 0.1.0 → 0.7.0

package/cli/bin/loom.js

@@ -1,17 +1,21 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // loom — LOOM 框架的 CLI 传感器层
 // Agent 通过这个 CLI 访问 Intent Map / 哲学 / 验证记录，不直接读文件。
 
 import { argv, cwd, exit } from 'node:process';
-import { resolve, join } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { findLoomRoot, findVersionDir, readCurrentPointer } from '../src/shared/paths.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 import { getNextIntent, getStatus, getDependencyGraph, getIntent, loadIntentMap, updateIntentStatus, getNarrative } from '../src/intent-map.js';
 import { getPhilosophy, listPhilosophyFiles } from '../src/philosophy.js';
 import { writeVerification, getVerificationHistory, getPendingVerifications, listVerifications, getVerificationContract } from '../src/verify.js';
 import { initProject } from '../src/init.js';
 import { activateRole } from '../src/activate.js';
-import { listVersions, readCurrentPointer, newVersion, useVersion, diffVersions } from '../src/version.js';
+import { listVersions, newVersion, useVersion, diffVersions } from '../src/version.js';
 import { doctor, contextSummary, traceIntent, reverseDep, reverseRef } from '../src/diagnostics.js';
 import { getHelpTopic, listHelpTopics } from '../src/help.js';
 import { guideProject } from '../src/guide.js';
@@ -19,42 +23,15 @@ import { isAutoOn, autoOn, autoOff, autoStatus } from '../src/auto.js';
 import { generatePreviewPrompt } from '../src/preview.js';
 
 // ─── 路径解析 ──────────────────────────────────────────
-// LOOM 项目目录结构: .loom/v{N}/
-// 优先读 .loom/current 指针；不存在则回退到自动探测最新版本。
-// 也接受 --loom-dir 参数直接指定版本目录。
-
-function findLoomRoot() {
-  const flagIdx = argv.indexOf('--loom-dir');
-  if (flagIdx !== -1 && argv[flagIdx + 1]) {
-    // --loom-dir 直接指向版本目录，反推 .loom root
-    const dir = resolve(argv[flagIdx + 1]);
-    return resolve(dir, '..');
-  }
-  return join(cwd(), '.loom');
-}
+// findLoomRoot / findVersionDir / readCurrentPointer 已提取到 shared/paths.js
+// 这里只保留目录辅助函数。
 
-function findLoomDir() {
-  const flagIdx = argv.indexOf('--loom-dir');
-  if (flagIdx !== -1 && argv[flagIdx + 1]) {
-    return resolve(argv[flagIdx + 1]);
-  }
-  const loomRoot = join(cwd(), '.loom');
-  if (!existsSync(loomRoot)) {
-    die(`找不到 .loom 目录: ${loomRoot}`);
-  }
-  const current = readCurrentPointer(loomRoot);
-  if (!current) {
-    die(`.loom 下没有版本目录 (v1, v2, ...)`);
-  }
-  return join(loomRoot, current);
-}
-
-function getPhilosophyDir(loomDir) {
-  return join(loomDir, '00_PHILOSOPHY');
+function getPhilosophyDir(versionDir) {
+  return join(versionDir, '00_PHILOSOPHY');
 }
 
-function getVerificationsDir(loomDir) {
-  return join(loomDir, 'verifications');
+function getVerificationsDir(versionDir) {
+  return join(versionDir, 'verifications');
 }
 
 // ─── 输出工具 ──────────────────────────────────────────
@@ -78,56 +55,66 @@ const [cmd, sub, ...rest] = argv.slice(2);
 
 try {
   switch (cmd) {
+    case '--version':
+    case '-v': {
+      // 从根 package.json 读版本号（cli/bin -> cli -> LOOM root）
+      const pkgPath = resolve(__dirname, '..', '..', 'package.json');
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      console.log(`loom ${pkg.version}`);
+      break;
+    }
+
     case 'intent': {
-      const loomDir = findLoomDir();
+      const versionDir = findVersionDir();
       switch (sub) {
         case 'next':
-          output(getNextIntent(loomDir) ?? '没有可执行的 Intent');
+          output(getNextIntent(versionDir) ?? '没有可执行的 Intent');
           break;
         case 'status': {
-          const s = getStatus(loomDir);
+          const s = getStatus(versionDir);
+          const fmt = (ids) => ids.map((id) => s.titles[id] ? `${id}(${s.titles[id]})` : id).join(', ') || '-';
           console.log(`进度: ${s.counts.completed}/${s.counts.total} 完成`);
-          console.log(`  pending:     ${s.counts.pending}    ${s.ids.pending.join(', ') || '-'}`);
-          console.log(`  in_progress: ${s.counts.in_progress}    ${s.ids.in_progress.join(', ') || '-'}`);
-          console.log(`  completed:   ${s.counts.completed}    ${s.ids.completed.join(', ') || '-'}`);
-          console.log(`  blocked:     ${s.counts.blocked}    ${s.ids.blocked.join(', ') || '-'}`);
+          console.log(`  pending:     ${s.counts.pending}    ${fmt(s.ids.pending)}`);
+          console.log(`  in_progress: ${s.counts.in_progress}    ${fmt(s.ids.in_progress)}`);
+          console.log(`  completed:   ${s.counts.completed}    ${fmt(s.ids.completed)}`);
+          console.log(`  blocked:     ${s.counts.blocked}    ${fmt(s.ids.blocked)}`);
           break;
         }
         case 'graph':
-          output(getDependencyGraph(loomDir));
+          output(getDependencyGraph(versionDir));
           break;
         case 'get': {
           const id = rest[0];
           if (!id) die('用法: loom intent get <id>');
-          output(getIntent(loomDir, id));
+          output(getIntent(versionDir, id));
           break;
         }
         case 'narrative': {
           const id = rest[0];
           if (!id) die('用法: loom intent narrative <id>');
-          output(getNarrative(loomDir, id));
+          output(getNarrative(versionDir, id));
           break;
         }
         case 'validate':
-          loadIntentMap(loomDir);
+          loadIntentMap(versionDir);
           console.log('Intent Map 校验通过');
           break;
         case 'trace': {
           const id = rest[0];
           if (!id) die('用法: loom intent trace <id>');
-          output(traceIntent(loomDir, getVerificationsDir(loomDir), getPhilosophyDir(loomDir), id));
+          output(traceIntent(versionDir, getVerificationsDir(versionDir), getPhilosophyDir(versionDir), id));
           break;
         }
         case 'reverse-dep': {
           const id = rest[0];
           if (!id) die('用法: loom intent reverse-dep <id>');
-          output(reverseDep(loomDir, id));
+          output(reverseDep(versionDir, id));
           break;
         }
         case 'reverse-ref': {
           const anchor = rest[0];
           if (!anchor) die('用法: loom intent reverse-ref <anchor>\n例: loom intent reverse-ref PRODUCT_PHILOSOPHY.md#core-belief');
-          output(reverseRef(loomDir, anchor));
+          output(reverseRef(versionDir, anchor));
           break;
         }
         case 'update': {
@@ -135,7 +122,7 @@ try {
           const statusFlagIdx = argv.indexOf('--status');
           const newStatus = statusFlagIdx !== -1 ? argv[statusFlagIdx + 1] : null;
           if (!id || !newStatus) die('用法: loom intent update <id> --status <pending|in_progress|completed|blocked|needs_review>');
-          updateIntentStatus(loomDir, id, newStatus);
+          updateIntentStatus(versionDir, id, newStatus);
           console.log(`${id} status 已更新为 ${newStatus}`);
           break;
         }
@@ -166,27 +153,32 @@ try {
     case 'activate': {
       const role = sub;
       if (!role) die('用法: loom activate <role>\n角色: weaver | visionary | architect | forge | keeper');
-      // weaver 不需要 loomDir（项目还没初始化时也能激活）
-      let loomDir = null;
+      // weaver 不需要 versionDir（项目还没初始化时也能激活）
+      let versionDir = null;
       if (role !== 'weaver') {
-        try { loomDir = findLoomDir(); } catch { /* 项目还没初始化，weaver 之外的角色会缺少项目上下文 */ }
+        try {
+          versionDir = findVersionDir();
+        } catch (e) {
+          // 只吞"找不到 .loom 目录"——其他错误（权限、磁盘）向上抛
+          if (!String(e.message).includes('找不到 .loom')) throw e;
+        }
       }
-      const prompt = activateRole(role, loomDir);
+      const prompt = activateRole(role, versionDir);
       output(prompt);
       break;
     }
 
     case 'philosophy': {
-      const loomDir = findLoomDir();
+      const versionDir = findVersionDir();
       switch (sub) {
         case 'get': {
           const anchor = rest[0];
           if (!anchor) die('用法: loom philosophy get <anchor>\n例: loom philosophy get PRODUCT_PHILOSOPHY.md#core-belief');
-          output(getPhilosophy(getPhilosophyDir(loomDir), anchor));
+          output(getPhilosophy(getPhilosophyDir(versionDir), anchor));
           break;
         }
         case 'list':
-          output(listPhilosophyFiles(getPhilosophyDir(loomDir)));
+          output(listPhilosophyFiles(getPhilosophyDir(versionDir)));
           break;
         default:
           die(`未知子命令: philosophy ${sub}\n用法: loom philosophy [get <anchor>|list]`);
@@ -195,13 +187,13 @@ try {
     }
 
     case 'verify': {
-      const loomDir = findLoomDir();
-      const verificationsDir = getVerificationsDir(loomDir);
+      const versionDir = findVersionDir();
+      const verificationsDir = getVerificationsDir(versionDir);
       switch (sub) {
         case 'contract': {
           const id = rest[0];
           if (!id) die('用法: loom verify contract <id>');
-          output(getVerificationContract(loomDir, id));
+          output(getVerificationContract(versionDir, id));
           break;
         }
         case 'history': {
@@ -212,7 +204,7 @@ try {
           break;
         }
         case 'pending':
-          output(getPendingVerifications(loomDir, verificationsDir));
+          output(getPendingVerifications(versionDir, verificationsDir));
           break;
         case 'list':
           output(listVerifications(verificationsDir));
@@ -224,9 +216,17 @@ try {
           const jsonFlagIdx = argv.indexOf('--json');
           let record;
           if (fileFlagIdx !== -1 && argv[fileFlagIdx + 1]) {
-            record = JSON.parse(readFileSync(argv[fileFlagIdx + 1], 'utf-8'));
+            try {
+              record = JSON.parse(readFileSync(argv[fileFlagIdx + 1], 'utf-8'));
+            } catch (e) {
+              die(`JSON 文件解析失败: ${argv[fileFlagIdx + 1]}\n原因: ${e.message}`);
+            }
           } else if (jsonFlagIdx !== -1 && argv[jsonFlagIdx + 1]) {
-            record = JSON.parse(argv[jsonFlagIdx + 1]);
+            try {
+              record = JSON.parse(argv[jsonFlagIdx + 1]);
+            } catch (e) {
+              die(`JSON 字符串解析失败: ${e.message}`);
+            }
           } else {
             die('用法: loom verify write --json-file <path> | --json <json-string>');
           }
@@ -298,8 +298,8 @@ try {
     }
 
     case 'doctor': {
-      const loomDir = findLoomDir();
-      const { issues, summary } = doctor(loomDir, getVerificationsDir(loomDir), getPhilosophyDir(loomDir));
+      const versionDir = findVersionDir();
+      const { issues, summary } = doctor(versionDir, getVerificationsDir(versionDir), getPhilosophyDir(versionDir));
       if (summary.healthy) {
         console.log('✓ 项目健康，未发现问题');
       } else {
@@ -313,8 +313,8 @@ try {
     }
 
     case 'context': {
-      const loomDir = findLoomDir();
-      output(contextSummary(loomDir, getVerificationsDir(loomDir), getPhilosophyDir(loomDir)));
+      const versionDir = findVersionDir();
+      output(contextSummary(versionDir, getVerificationsDir(versionDir), getPhilosophyDir(versionDir)));
       break;
     }
 
@@ -361,6 +361,9 @@ try {
         case 'on':
           autoOn(loomRoot);
           console.log('AUTO 模式已开启。Agent 将自动连续执行，不等用户确认。');
+          console.log('核心契约: 持续运行，除非出意外否则不允许私自停止。');
+          console.log('  - L3 human_review 由 Keeper 自主判定，不停下等人类');
+          console.log('  - 唯一允许停下的情况: blocked（依赖阻塞/契约无法判定/连续 3 轮 deviated 升级）');
           console.log('关闭: loom auto off');
           break;
         case 'off':
@@ -371,8 +374,18 @@ try {
           const status = autoStatus(loomRoot);
           if (status.on) {
             console.log(`AUTO 模式: 开启（自 ${status.since}）`);
+            console.log('  规则: stage 1-3（哲学/愿景/架构）需人类 review，stage 4+（Intent Loop）自动执行');
+            if (status.heartbeat) {
+              const hb = status.heartbeat;
+              console.log(`  心跳: ${hb.timestamp}`);
+              console.log(`    阶段: ${hb.stage} (stage ${hb.stage_num})`);
+              console.log(`    下一步: ${hb.next_action}`);
+              console.log(`    命令: ${hb.next_command}`);
+            } else {
+              console.log('  心跳: 尚未记录（运行 loom guide 后生成）');
+            }
           } else {
-            console.log('AUTO 模式: 关闭');
+            console.log('AUTO 模式: 关闭（所有阶段都需人类确认）');
           }
           break;
         }
@@ -383,10 +396,31 @@ try {
     }
 
     case 'preview': {
-      // 输出提示词，让 AI 读 .loom/ 文件、重组信息、生成 HTML
+      const previewFile = join(cwd(), 'loom-preview.html');
+      const hasPreview = existsSync(previewFile);
+      const regenOnly = argv.includes('--regen') || argv.includes('-r');
+
+      // 已有 HTML 且没指定 --regen：直接打开浏览器
+      if (hasPreview && !regenOnly) {
+        const { spawn } = await import('node:child_process');
+        const target = previewFile.replace(/\\/g, '/');
+        if (process.platform === 'win32') {
+          spawn('cmd', ['/c', 'start', target], { detached: true, stdio: 'ignore' }).unref();
+        } else if (process.platform === 'darwin') {
+          spawn('open', [target], { detached: true, stdio: 'ignore' }).unref();
+        } else {
+          spawn('xdg-open', [target], { detached: true, stdio: 'ignore' }).unref();
+        }
+        console.log(`已打开浏览器: ${previewFile}`);
+        console.log(`重新生成: loom preview --regen`);
+        break;
+      }
+
+      // 没有 HTML 或指定 --regen：输出提示词让 AI 生成
       const prompt = generatePreviewPrompt();
       console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
       console.log('To Agent: 按以下提示词读 .loom/ 文件并生成 loom-preview.html');
+      console.log('  生成完成后再次运行 loom preview 会自动打开浏览器');
       console.log('To Human: 把以下内容给你的 AI agent');
       console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
       console.log('');
@@ -440,7 +474,8 @@ To Human:
 
   loom doctor                   项目健康检查（一致性+孤儿引用+循环依赖+僵尸）
   loom context                  上下文摘要（进度+下一步+待验证+风险）
-  loom preview                  输出提示词+数据，让 AI 生成 HTML 可视化预览
+  loom preview                  已有 HTML 则打开浏览器，否则输出提示词让 AI 生成
+  loom preview --regen          强制重新输出提示词（让 AI 重新生成 HTML）
   loom help <topic>             分层指南（workflow|concepts|loop|version|doctor）
 
   loom philosophy get <anchor>  按锚点加载哲学章节

package/cli/help/concepts.md

@@ -0,0 +1,72 @@
+## LOOM 核心概念
+
+## 哲学
+
+项目的价值观和工程原则——为什么存在、什么不做、冲突时谁优先。
+由 Philosophy Weaver 从真实思想体系织造，不是模板填空。
+所有角色激活时强制加载哲学作为共同锚点。
+
+相关命令：
+- \`loom philosophy get <anchor>\` — 加载哲学章节
+- \`loom philosophy list\` — 列出哲学文档
+- \`loom intent reverse-ref <anchor>\` — 哪些 Intent 引用了这个哲学锚点
+
+## Intent
+
+一个意图单元——不是"做什么"（任务），是"为什么做"（意图）。
+每个 Intent 携带：
+- narrative_ref — 意图叙事引用（为什么存在）
+- depends_on — 依赖的 Intent（拓扑序）
+- acceptance — 验收契约（Keeper 据此判定）
+- philosophy_anchors — 哲学锚点（引用哪些哲学原则）
+- status — 状态（pending|in_progress|completed|blocked|needs_review）
+- verification_method — 验证方式（L1 静态|L2 运行时|L3 人类反馈，可选）
+
+相关命令：
+- \`loom intent next\` — 下一个可执行 Intent
+- \`loom intent get <id>\` — Intent 详情
+- \`loom intent narrative <id>\` — 意图叙事
+- \`loom intent trace <id>\` — 完整追溯链
+- \`loom intent reverse-dep <id>\` — 谁依赖这个 Intent
+
+## Intent Map
+
+所有 Intent 的依赖图（JSON）。Architect 绘制，定义拓扑序和依赖关系。
+必须是 DAG（有向无环图），不能有循环依赖。
+
+相关命令：
+- \`loom intent validate\` — 校验结构 + 依赖一致性
+- \`loom intent graph\` — Mermaid 依赖图
+- \`loom intent status\` — 进度概览
+
+## Intent Loop
+
+核心循环：Keeper 选 Intent → Forge 实现 → Keeper 验证 → 闭合或修正。
+每个 Intent 独立走一圈。详细流程见 \`loom help loop\`。
+
+## Keeper
+
+独立验证子代理——不继承 Forge 的实现上下文，从磁盘重新加载意图和契约。
+判定四维度：意图忠实度 / 哲学一致性 / 底线合规 / 验收达成。
+判定结果：passed / deviated / blocked / pending_human。
+
+## 底线
+
+不可妥协的约束（BASELINE.md 5 条 + 项目特定底线）。
+角色激活时强制加载，哲学不能覆盖。违反底线必须立即停止。
+
+## 验证记录
+
+Keeper 每次验证写入一条记录（追加模式），包含：
+- verdict（passed/deviated/blocked/pending_human）
+- 四维度判定
+- 证据
+- 偏离说明（如果 deviated）
+
+deviated 连续 3 轮升级 blocked。pending_human 默认 7 天超时升级 blocked。
+
+相关命令：
+- \`loom verify contract <id>\` — 获取验收契约
+- \`loom verify write --json-file <path>\` — 写入验证记录
+- \`loom verify history <id>\` — 验证历史
+- \`loom verify pending\` — 待验证的 Intent

package/cli/help/doctor.md

@@ -0,0 +1,70 @@
+## 诊断与恢复指南
+
+## 健康检查
+
+\`\`\`bash
+loom doctor
+\`\`\`
+
+检测 6 类问题：
+
+| 问题类型 | 严重度 | 说明 |
+|---|---|---|
+| cycle | fatal | 循环依赖（Intent Map 有环） |
+| orphan_philosophy_ref | high | 哲学锚点指向不存在的文件 |
+| orphan_dependency | high | depends_on 引用不存在的 Intent |
+| completed_no_record | high | completed 但无验证记录 |
+| completed_depends_blocked | high | completed 依赖 blocked 的 Intent |
+| in_progress_no_record | medium | in_progress 但无验证记录（可能中断） |
+| zombie | medium | in_progress/blocked 超过 7 天无活动 |
+
+## 上下文摘要
+
+\`\`\`bash
+loom context
+\`\`\`
+
+一条命令获取：进度 + 下一个 Intent + 待验证 + 不一致项 + 风险。
+Agent 重启后先跑这个，快速知道"我在哪、接下来做什么"。
+
+## 崩溃恢复
+
+### Forge 崩溃（Intent 留在 in_progress）
+
+1. 跑 \`loom doctor\` 确认哪些 Intent 状态不一致
+2. 跑 \`loom context\` 看整体状态
+3. 用户决定：
+   - 继续：重新激活 Forge，从当前代码接着做
+   - 重置：\`loom intent update <id> --status pending\`，从头来
+
+### Intent Map 文件损坏
+
+1. \`loom intent validate\` 会检测到格式错误
+2. 从 Git 恢复（.loom/ 应纳入版本控制）
+
+### 验证记录丢失
+
+1. \`loom doctor\` 会检测到 completed 无记录
+2. 重新验证该 Intent，或从 Git 恢复
+
+## 追溯工具
+
+\`\`\`bash
+# Intent 完整追溯链（依赖+验证+哲学+叙事）
+loom intent trace <id>
+
+# 反向依赖（谁依赖这个 Intent → 变更影响评估）
+loom intent reverse-dep <id>
+
+# 反向哲学引用（哪些 Intent 引用这个锚点 → 哲学变更影响评估）
+loom intent reverse-ref <anchor>
+\`\`\`
+
+## 版本控制是前提
+
+LOOM 假设项目使用 Git。所有 .loom/ 下的文件都应纳入版本控制：
+- 文件损坏 → 从 Git 恢复
+- 误操作 → 从 Git 回滚
+- 变更追溯 → Git log 就是审计日志
+
+LOOM 不内置备份、审计、回滚——这些是版本控制的职责。

package/cli/help/loop.md

@@ -0,0 +1,135 @@
+## Intent Loop 详细流程
+
+每个 Intent 独立走一圈。Loop 终止条件：所有 Intent 为 completed 且无 needs_review（不动点达成）。
+
+## Step 1：Keeper 选 Intent
+
+\`\`\`bash
+loom intent next          # 返回下一个可执行 Intent（pending 且依赖都 completed）
+loom context              # 当前状态摘要（进度+下一步+风险）
+\`\`\`
+
+如果没有可执行的 Intent：
+- 全部 completed → 项目阶段完成
+- 有 blocked → 需要人工介入
+- 有 in_progress 但无验证记录 → 可能上次中断，跑 \`loom doctor\` 诊断
+
+## Step 2：更新状态
+
+\`\`\`bash
+loom intent update <id> --status in_progress
+\`\`\`
+
+## Step 3：Forge 实现
+
+\`\`\`bash
+loom activate forge
+\`\`\`
+
+Forge 加载：意图叙事 + 哲学锚点 + 验收契约，在约束下自主实现代码。
+辅助命令（三个命令的分工）：
+- \`loom intent narrative <id>\` — 读意图叙事（"为什么做"）
+- \`loom verify contract <id>\` — 读验收契约（"做成什么样才算数"）
+- \`loom intent trace <id>\` — 完整追溯链（叙事+契约+哲学锚点一次性加载，最常用）
+- \`loom philosophy get <anchor>\` — 读哲学原则（遇到取舍时查）
+
+## Step 4：Keeper 验证
+
+\`\`\`bash
+loom activate keeper
+loom verify contract <id>     # 重新加载验收契约
+\`\`\`
+
+Keeper 独立验证四维度：
+1. 意图忠实度 — 实现是否忠于原始意图叙事
+2. 哲学一致性 — 实现是否符合哲学原则
+3. 底线合规 — 是否违反 BASELINE
+4. 验收达成 — 是否满足验收契约
+
+写入验证记录：
+\`\`\`bash
+loom verify write --json-file verification.json
+\`\`\`
+
+验证记录格式（\`loom verify write\` 的输入）：
+\`\`\`json
+{
+  "intent_id": "INT-001",
+  "verdict": "passed",
+  "timestamp": "2026-06-28T12:00:00.000Z",
+  "summary": "具体证据描述——不是'看起来没问题'",
+  "reproduction_command": "LLM_API_KEY=mock npm test",
+  "dimensions": {
+    "intent_fidelity": {
+      "verdict": "passed",
+      "evidence": "对照意图叙事第 2 段，extract.js 实现了完整编排"
+    },
+    "philosophy_consistency": {
+      "verdict": "passed",
+      "evidence": "AI_PHILOSOPHY 反模式逐条对照：JSON.parse 有 try/catch、fetch 有超时、无硬编码密钥"
+    },
+    "baseline_compliance": {
+      "verdict": "passed",
+      "evidence": "B1-B5 逐条合规"
+    },
+    "acceptance_achievement": {
+      "verdict": "passed",
+      "evidence": "6 条契约全部达成，npm test 6/6 pass"
+    }
+  }
+}
+\`\`\`
+CLI 自动包装成 \`{ intent_id, records: [{ round, ... }] }\` 追加到验证文件。
+\`dimensions\` 每个维度必须是 \`{ verdict, evidence }\` 对象——不允许只写"合规"，必须写具体证据。
+\`reproduction_command\` 是复现验证的命令——别人跑这个命令能复现你的验证结果。L2 必填。
+
+**evidence 写法参考**：
+- 长度：每条 evidence 50-300 字符为宜。太短（"合规"）不达标，太长难读。
+- 哲学一致性维度：按哲学锚点逐条对照反模式（见 keeper.md 的"承诺验证法"）
+- 其他维度：写"对照了什么 + 在代码哪里看到/没看到"
+- \`reproduction_command\` 注意平台差异：
+  - Unix/Mac: \`LLM_API_KEY=mock npm test\`
+  - Windows PowerShell: \`$env:LLM_API_KEY='mock'; npm test\`
+  - Windows cmd: \`set LLM_API_KEY=mock && npm test\`
+- \`node --test\` 在 Windows 上不能用目录路径（\`node --test test/\` 会报错），用 glob：\`node --test test/*.test.js\`
+
+## Step 5：根据判定结果
+
+| verdict | 处理 |
+|---|---|
+| passed | \`loom intent update <id> --status completed\`，回到 Step 1 |
+| deviated | 与 Forge 对话修正，重新实现重新验证。连续 3 轮升级 blocked |
+| blocked | \`loom intent update <id> --status blocked\`，停下报告用户 |
+| pending_human | **手动模式**：等用户补充判定（L3 人类反馈）。7 天超时升级 blocked |
+
+**AUTO 模式下的判定规则**（关键差异）：
+- AUTO 模式开启时（\`loom auto on\`），**不允许 pending_human**
+- Keeper 遇到 L3 verification_method 时，用 L1+L2 能耐自主判定所有维度
+- 要么 passed（有证据），要么 deviated（有偏离说明），不停下等人类
+- **持续运行，除非出意外否则不允许私自停止**
+- "出意外" = blocked（依赖阻塞/契约无法判定/连续 3 轮 deviated 升级）、fatal 错误
+
+## 变更回流
+
+如果 Forge 发现验收契约不合理、或 Architect 的设计需要调整：
+1. Keeper 评估变更范围（微调 vs 结构性变更）
+2. 微调（验收措辞、验证方式）→ Keeper 直接改
+3. 结构性变更（增减 Intent、改依赖）→ 重新激活 Architect
+4. 受影响的已完成 Intent 标记为 needs_review
+
+## 不动点收敛
+
+默认单趟：所有 Intent 按拓扑序验证完毕且全 passed → done。
+
+触发收敛：Pass 1 结束后还有 needs_review 的 Intent → 自动进入 Pass 2。
+- Pass 2: 重验所有 needs_review 的 Intent
+  - deviated → 修 → 重验
+  - 修的时候又影响别的 → 标记 needs_review
+  - passed → completed
+- Pass 2 结束还有 needs_review → Pass 3
+- Pass 3 结束还有 needs_review → blocked，报告"无法收敛"
+
+收敛达成 = 一趟完整 pass 没有产生任何新的 needs_review（不动点）。
+最大 3 趟，超过判定为系统性问题，需 Architect 介入。
+
+详细规则见 .loom/v{N}/ 下的 INTENT_LOOP.md。

package/cli/help/version.md

@@ -0,0 +1,60 @@
+## 版本演进指南
+
+LOOM 用 .loom/v{N}/ 目录支持多版本共存与演进。
+
+## 什么时候升级版本
+
+| 变更类型 | 判定标准 | 处理方式 |
+|---|---|---|
+| Minor | 不改哲学前提、不改愿景北极星、不改架构边界 | 当前版本内改（变更回流机制） |
+| Major | 哲学前提变了、愿景北极星变了、架构边界变了 | 创建新版本 |
+
+判定由用户 + Agent 对话完成，CLI 不做决策。
+
+## Major 升级流程
+
+\`\`\`bash
+# 1. 创建新版本（空目录 + 模板，自动切换为当前）
+loom version new
+
+# 2. 看看旧版本有什么（Agent 决定参考什么）
+loom version diff v1 v2
+
+# 3. Weaver 读旧哲学，织造新哲学
+loom activate weaver
+# → 必须读 .loom/v1/00_PHILOSOPHY/，记录"相对 v1 变了什么"
+
+# 4. Visionary 读旧愿景，定义新愿景
+loom activate visionary
+# → 必须读 .loom/v1/01_VISION.md
+
+# 5. Architect 读旧架构，设计新架构
+loom activate architect
+# → 必须读 .loom/v1/02_ARCHITECTURE.md + 04_INTENT_MAP.json
+
+# 6. 进入新版本的 Intent Loop
+\`\`\`
+
+## 关键设计
+
+- **空目录 + 模板**：\`loom version new\` 不自动复制旧版本内容。强制重新思考——参考 ≠ 复制。
+- **旧版本只读**：当前指针指向的版本是当前真相，旧版本保留作历史参考。
+- **Intent ID 重新编号**：v2 的 INT-001 和 v1 的 INT-001 没有关系。追溯靠 Git history 和 \`loom version diff\`。
+
+## 版本管理命令
+
+\`\`\`bash
+loom version list              # 列出所有版本（* 标记当前）
+loom version current           # 显示当前版本
+loom version new               # 创建 v{N+1} + 自动切换
+loom version use <v>           # 切换当前版本
+loom version diff <v1> <v2>    # 对比文件差异
+\`\`\`
+
+## 切换回旧版本
+
+\`\`\`bash
+loom version use v1            # 切回 v1 查看历史
+loom intent trace <id>         # 在 v1 中追溯 Intent 历史
+loom version use v2            # 切回 v2 继续
+\`\`\`